idnits 2.17.1 draft-ietf-taps-interface-14.txt: -(3674): 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 copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (3 January 2022) is 842 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 517, but not defined == Missing Reference: 'StunCandidate' is mentioned on line 517, but not defined == Outdated reference: A later version (-19) exists of draft-ietf-taps-arch-11 ** Obsolete normative reference: RFC 4941 (Obsoleted by RFC 8981) ** Downref: Normative reference to an Informational RFC: RFC 8303 == Outdated reference: A later version (-12) exists of draft-ietf-httpbis-priority-11 == Outdated reference: A later version (-18) exists of draft-ietf-taps-impl-10 -- Obsolete informational reference (is this intentional?): RFC 5245 (Obsoleted by RFC 8445, RFC 8839) -- Obsolete informational reference (is this intentional?): RFC 5766 (Obsoleted by RFC 8656) -- Obsolete informational reference (is this intentional?): RFC 8229 (Obsoleted by RFC 9329) Summary: 4 errors (**), 0 flaws (~~), 7 warnings (==), 4 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: 7 July 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 C.A. Wood 17 Cloudflare 18 T. Pauly 19 Apple Inc. 20 K. Rose 21 Akamai Technologies, Inc. 22 3 January 2022 24 An Abstract Application Layer Interface to Transport Services 25 draft-ietf-taps-interface-14 27 Abstract 29 This document describes an abstract application programming 30 interface, API, to the transport layer that enables the selection of 31 transport protocols and network paths dynamically at runtime. This 32 API enables faster deployment of new protocols and protocol features 33 without requiring changes to the applications. The specified API 34 follows the Transport Services architecture by providing 35 asynchronous, atomic transmission of messages. It is intended to 36 replace the BSD sockets API as the common interface to the transport 37 layer, in an environment where endpoints could select from multiple 38 interfaces and potential transport protocols. 40 Status of This Memo 42 This Internet-Draft is submitted in full conformance with the 43 provisions of BCP 78 and BCP 79. 45 Internet-Drafts are working documents of the Internet Engineering 46 Task Force (IETF). Note that other groups may also distribute 47 working documents as Internet-Drafts. The list of current Internet- 48 Drafts is at https://datatracker.ietf.org/drafts/current/. 50 Internet-Drafts are draft documents valid for a maximum of six months 51 and may be updated, replaced, or obsoleted by other documents at any 52 time. It is inappropriate to use Internet-Drafts as reference 53 material or to cite them other than as "work in progress." 55 This Internet-Draft will expire on 7 July 2022. 57 Copyright Notice 59 Copyright (c) 2022 IETF Trust and the persons identified as the 60 document authors. All rights reserved. 62 This document is subject to BCP 78 and the IETF Trust's Legal 63 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 64 license-info) in effect on the date of publication of this document. 65 Please review these documents carefully, as they describe your rights 66 and restrictions with respect to this document. Code Components 67 extracted from this document must include Revised BSD License text as 68 described in Section 4.e of the Trust Legal Provisions and are 69 provided without warranty as described in the Revised BSD License. 71 Table of Contents 73 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 74 1.1. Terminology and Notation . . . . . . . . . . . . . . . . 5 75 1.2. Specification of Requirements . . . . . . . . . . . . . . 7 76 2. Overview of the API Design . . . . . . . . . . . . . . . . . 7 77 3. API Summary . . . . . . . . . . . . . . . . . . . . . . . . . 8 78 3.1. Usage Examples . . . . . . . . . . . . . . . . . . . . . 9 79 3.1.1. Server Example . . . . . . . . . . . . . . . . . . . 9 80 3.1.2. Client Example . . . . . . . . . . . . . . . . . . . 10 81 3.1.3. Peer Example . . . . . . . . . . . . . . . . . . . . 12 82 4. Transport Properties . . . . . . . . . . . . . . . . . . . . 13 83 4.1. Transport Property Names . . . . . . . . . . . . . . . . 14 84 4.2. Transport Property Types . . . . . . . . . . . . . . . . 15 85 5. Scope of the API Definition . . . . . . . . . . . . . . . . . 15 86 6. Pre-Establishment Phase . . . . . . . . . . . . . . . . . . . 16 87 6.1. Specifying Endpoints . . . . . . . . . . . . . . . . . . 17 88 6.1.1. Using Multicast Endpoints . . . . . . . . . . . . . . 19 89 6.1.2. Constraining Interfaces for Endpoints . . . . . . . . 19 90 6.1.3. Endpoint Aliases . . . . . . . . . . . . . . . . . . 20 91 6.1.4. Endpoint Examples . . . . . . . . . . . . . . . . . . 20 92 6.1.5. Multicast Examples . . . . . . . . . . . . . . . . . 21 93 6.2. Specifying Transport Properties . . . . . . . . . . . . . 23 94 6.2.1. Reliable Data Transfer (Connection) . . . . . . . . . 26 95 6.2.2. Preservation of Message Boundaries . . . . . . . . . 27 96 6.2.3. Configure Per-Message Reliability . . . . . . . . . . 27 97 6.2.4. Preservation of Data Ordering . . . . . . . . . . . . 27 98 6.2.5. Use 0-RTT Session Establishment with a Safely 99 Replayable Message . . . . . . . . . . . . . . . . . 27 100 6.2.6. Multistream Connections in Group . . . . . . . . . . 28 101 6.2.7. Full Checksum Coverage on Sending . . . . . . . . . . 28 102 6.2.8. Full Checksum Coverage on Receiving . . . . . . . . . 28 103 6.2.9. Congestion control . . . . . . . . . . . . . . . . . 29 104 6.2.10. Keep alive . . . . . . . . . . . . . . . . . . . . . 29 105 6.2.11. Interface Instance or Type . . . . . . . . . . . . . 29 106 6.2.12. Provisioning Domain Instance or Type . . . . . . . . 30 107 6.2.13. Use Temporary Local Address . . . . . . . . . . . . . 31 108 6.2.14. Multipath Transport . . . . . . . . . . . . . . . . . 32 109 6.2.15. Advertisement of Alternative Addresses . . . . . . . 33 110 6.2.16. Direction of communication . . . . . . . . . . . . . 33 111 6.2.17. Notification of ICMP soft error message arrival . . . 34 112 6.2.18. Initiating side is not the first to write . . . . . . 34 113 6.3. Specifying Security Parameters and Callbacks . . . . . . 35 114 6.3.1. Specifying Security Parameters on a Pre-Connection . 35 115 6.3.2. Connection Establishment Callbacks . . . . . . . . . 37 116 7. Establishing Connections . . . . . . . . . . . . . . . . . . 37 117 7.1. Active Open: Initiate . . . . . . . . . . . . . . . . . . 37 118 7.2. Passive Open: Listen . . . . . . . . . . . . . . . . . . 39 119 7.3. Peer-to-Peer Establishment: Rendezvous . . . . . . . . . 40 120 7.4. Connection Groups . . . . . . . . . . . . . . . . . . . . 42 121 7.5. Adding and Removing Endpoints on a Connection . . . . . . 43 122 8. Managing Connections . . . . . . . . . . . . . . . . . . . . 44 123 8.1. Generic Connection Properties . . . . . . . . . . . . . . 46 124 8.1.1. Required Minimum Corruption Protection Coverage for 125 Receiving . . . . . . . . . . . . . . . . . . . . . . 46 126 8.1.2. Connection Priority . . . . . . . . . . . . . . . . . 46 127 8.1.3. Timeout for Aborting Connection . . . . . . . . . . . 47 128 8.1.4. Timeout for keep alive packets . . . . . . . . . . . 47 129 8.1.5. Connection Group Transmission Scheduler . . . . . . . 47 130 8.1.6. Capacity Profile . . . . . . . . . . . . . . . . . . 48 131 8.1.7. Policy for using Multipath Transports . . . . . . . . 49 132 8.1.8. Bounds on Send or Receive Rate . . . . . . . . . . . 50 133 8.1.9. Group Connection Limit . . . . . . . . . . . . . . . 51 134 8.1.10. Isolate Session . . . . . . . . . . . . . . . . . . . 51 135 8.1.11. Read-only Connection Properties . . . . . . . . . . . 51 136 8.2. TCP-specific Properties: User Timeout Option (UTO) . . . 52 137 8.2.1. Advertised User Timeout . . . . . . . . . . . . . . . 53 138 8.2.2. User Timeout Enabled . . . . . . . . . . . . . . . . 53 139 8.2.3. Timeout Changeable . . . . . . . . . . . . . . . . . 53 140 8.3. Connection Lifecycle Events . . . . . . . . . . . . . . . 54 141 8.3.1. Soft Errors . . . . . . . . . . . . . . . . . . . . . 54 142 8.3.2. Path change . . . . . . . . . . . . . . . . . . . . . 54 143 9. Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . 54 144 9.1. Messages and Framers . . . . . . . . . . . . . . . . . . 54 145 9.1.1. Message Contexts . . . . . . . . . . . . . . . . . . 55 146 9.1.2. Message Framers . . . . . . . . . . . . . . . . . . . 55 147 9.1.3. Message Properties . . . . . . . . . . . . . . . . . 57 148 9.2. Sending Data . . . . . . . . . . . . . . . . . . . . . . 63 149 9.2.1. Basic Sending . . . . . . . . . . . . . . . . . . . . 63 150 9.2.2. Send Events . . . . . . . . . . . . . . . . . . . . . 64 151 9.2.3. Partial Sends . . . . . . . . . . . . . . . . . . . . 65 152 9.2.4. Batching Sends . . . . . . . . . . . . . . . . . . . 66 153 9.2.5. Send on Active Open: InitiateWithSend . . . . . . . . 66 154 9.2.6. Priority and the Transport Services API . . . . . . . 67 155 9.3. Receiving Data . . . . . . . . . . . . . . . . . . . . . 67 156 9.3.1. Enqueuing Receives . . . . . . . . . . . . . . . . . 67 157 9.3.2. Receive Events . . . . . . . . . . . . . . . . . . . 68 158 9.3.3. Receive Message Properties . . . . . . . . . . . . . 71 159 10. Connection Termination . . . . . . . . . . . . . . . . . . . 72 160 11. Connection State and Ordering of Operations and Events . . . 73 161 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 75 162 13. Privacy and Security Considerations . . . . . . . . . . . . . 75 163 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 77 164 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 77 165 15.1. Normative References . . . . . . . . . . . . . . . . . . 77 166 15.2. Informative References . . . . . . . . . . . . . . . . . 78 167 Appendix A. Implementation Mapping . . . . . . . . . . . . . . . 81 168 A.1. Types . . . . . . . . . . . . . . . . . . . . . . . . . . 82 169 A.2. Events and Errors . . . . . . . . . . . . . . . . . . . . 82 170 A.3. Time Duration . . . . . . . . . . . . . . . . . . . . . . 82 171 Appendix B. Convenience Functions . . . . . . . . . . . . . . . 83 172 B.1. Adding Preference Properties . . . . . . . . . . . . . . 83 173 B.2. Transport Property Profiles . . . . . . . . . . . . . . . 83 174 B.2.1. reliable-inorder-stream . . . . . . . . . . . . . . . 83 175 B.2.2. reliable-message . . . . . . . . . . . . . . . . . . 84 176 B.2.3. unreliable-datagram . . . . . . . . . . . . . . . . . 84 177 Appendix C. Relationship to the Minimal Set of Transport Services 178 for End Systems . . . . . . . . . . . . . . . . . . . . . 85 179 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 88 181 1. Introduction 183 This document specifies an abstract application programming interface 184 (API) that specifies the interface component of the high-level 185 Transport Services architecture defined in [I-D.ietf-taps-arch]. A 186 Transport Services system supports asynchronous, atomic transmission 187 of messages over transport protocols and network paths dynamically 188 selected at runtime, in environments where an endpoint selects from 189 multiple interfaces and potential transport protocols. 191 Applications that adopt this API will benefit from a wide set of 192 transport features that can evolve over time. This protocol- 193 independent API ensures that the system providing the API can 194 optimize its behavior based on the application requirements and 195 network conditions, without requiring changes to the applications. 196 This flexibility enables faster deployment of new features and 197 protocols, and can support applications by offering racing and 198 fallback mechanisms, which otherwise need to be separately 199 implemented in each application. 201 The Transport Services system derives specific path and protocol 202 selection properties and supported transport features from the 203 analysis provided in [RFC8095], [RFC8923], and [RFC8922]. The 204 Transport Services API enables an implementation to dynamically 205 choose a transport protocol rather than statically binding 206 applications to a protocol at compile time. The Transport Services 207 API also provides applications with a way to override transport 208 selection and instantiate a specific stack, e.g., to support servers 209 wishing to listen to a specific protocol. However, forcing a choice 210 to use a specific transport stack is discouraged for general use, 211 because it can reduce portability. 213 1.1. Terminology and Notation 215 The Transport Services API is described in terms of 217 * Objects with which an application can interact; 219 * Actions the application can perform on these Objects; 221 * Events, which an Object can send to an application to be processed 222 aynchronously; and 224 * Parameters associated with these Actions and Events. 226 The following notations, which can be combined, are used in this 227 document: 229 * An Action that creates an Object: 231 Object := Action() 233 * An Action that creates an array of Objects: 235 []Object := Action() 237 * An Action that is performed on an Object: 239 Object.Action() 241 * An Object sends an Event: 243 Object -> Event<> 245 * An Action takes a set of Parameters; an Event contains a set of 246 Parameters. Action and Event parameters whose names are suffixed 247 with a question mark are optional. 249 Action(param0, param1?, ...) / Event 251 Objects that are passed as parameters to Actions use call-by-value 252 behavior. Actions associated with no Object are Actions on the API; 253 they are equivalent to Actions on a per-application global context. 255 Events are sent to the application or application-supplied code (e.g. 256 framers, see Section 9.1.2) for processing; the details of event 257 processing are platform- and implementation-specific. 259 We also make use of the following basic types: 261 * Boolean: Instances take the value true or false. 263 * Integer: Instances take positive or negative integer values. 265 * Numeric: Instances take positive or negative real number values. 267 * Enumeration: A family of types in which each instance takes one of 268 a fixed, predefined set of values specific to a given enumerated 269 type. 271 * Tuple: An ordered grouping of multiple value types, represented as 272 a comma-separated list in parentheses, e.g., (Enumeration, 273 Preference). Instances take a sequence of values each valid for 274 the corresponding value type. 276 * Array: Denoted []Type, an instance takes a value for each of zero 277 or more elements in a sequence of the given Type. An array may be 278 of fixed or variable length. 280 * Collection: An unordered grouping of one or more values of the 281 same type. 283 For guidance on how these abstract concepts may be implemented in 284 languages in accordance with native design patterns and language and 285 platform features, see Appendix A. 287 1.2. Specification of Requirements 289 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 290 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 291 "OPTIONAL" in this document are to be interpreted as described in BCP 292 14 [RFC2119] [RFC8174] when, and only when, they appear in all 293 capitals, as shown here. 295 2. Overview of the API Design 297 The design of the API specified in this document is based on a set of 298 principles, themselves an elaboration on the architectural design 299 principles defined in [I-D.ietf-taps-arch]. The API defined in this 300 document provides: 302 * A Transport Services system can offer a variety of transport 303 protocols, independent of the Protocol Stacks that will be used at 304 runtime. All common features of these protocol stacks are made 305 available to the application in a transport-independent way to the 306 degree possible. This enables applications written to a single 307 API to make use of transport protocols in terms of the features 308 they provide. 310 * A unified API to datagram and stream-oriented transports, allowing 311 use of a common API for connection establishment and closing. 313 * Message-orientation, as opposed to stream-orientation, using 314 application-assisted framing and deframing where the underlying 315 transport does not provide these. 317 * Asynchronous Connection establishment, transmission, and 318 reception. This allows concurrent operations during establishment 319 and event-driven application interactions with the transport 320 layer; 322 * Selection between alternate network paths, using additional 323 information about the networks over which a connection can operate 324 (e.g. Provisioning Domain (PvD) information [RFC7556]) where 325 available. 327 * Explicit support for transport-specific features to be applied, 328 should that particular transport be part of a chosen Protocol 329 Stack. 331 * Explicit support for security properties as first-order transport 332 features. 334 * Explicit support for configuration of cryptographic identities and 335 transport security parameters persistent across multiple 336 Connections. 338 * Explicit support for multistreaming and multipath transport 339 protocols, and the grouping of related Connections into Connection 340 Groups through "cloning" of Connections (see Section 7.4). This 341 function allows applications to take full advantage of new 342 transport protocols supporting these features. 344 3. API Summary 346 An application primarily interacts with this API through two Objects: 347 Preconnections and Connections. A Preconnection object (Section 6) 348 represents a set of properties and constraints on the selection and 349 configuration of paths and protocols to establish a Connection with 350 an Endpoint. A Connection object represents an instance of a 351 transport Protocol Stack on which data can be sent to and/or received 352 from a Remote Endpoint (i.e., a logical connection that, depending on 353 the kind of transport, can be bi-directional or unidirectional, and 354 that can use a stream protocol or a datagram protocol). Connections 355 are presented consistently to the application, irrespective of 356 whether the underlying transport is connection-less or connection- 357 oriented. Connections can be created from Preconnections in three 358 ways: 360 * by initiating the Preconnection (i.e., actively opening, as in a 361 client; Section 7.1), 363 * through listening on the Preconnection (i.e., passively opening, 364 as in a server Section 7.2), 366 * or rendezvousing on the Preconnection (i.e., peer to peer 367 establishment; Section 7.3). 369 Once a Connection is established, data can be sent and received on it 370 in the form of Messages. The API supports the preservation of 371 message boundaries both via explicit Protocol Stack support, and via 372 application support through a Message Framer that finds message 373 boundaries in a stream. Messages are received asynchronously through 374 event handlers registered by the application. Errors and other 375 notifications also happen asynchronously on the Connection. It is 376 not necessary for an application to handle all Events; some Events 377 may have implementation-specific default handlers. The application 378 should not assume that ignoring Events (e.g., Errors) is always safe. 380 3.1. Usage Examples 382 The following usage examples illustrate how an application might use 383 the Transport Services API to: 385 * Act as a server, by listening for incoming connections, receiving 386 requests, and sending responses, see Section 3.1.1. 388 * Act as a client, by connecting to a Remote Endpoint using 389 Initiate, sending requests, and receiving responses, see 390 Section 3.1.2. 392 * Act as a peer, by connecting to a Remote Endpoint using Rendezvous 393 while simultaneously waiting for incoming Connections, sending 394 Messages, and receiving Messages, see Section 3.1.3. 396 The examples in this section presume that a transport protocol is 397 available between the Local and Remote Endpoints that provides 398 Reliable Data Transfer, Preservation of Data Ordering, and 399 Preservation of Message Boundaries. In this case, the application 400 can choose to receive only complete messages. 402 If none of the available transport protocols provides Preservation of 403 Message Boundaries, but there is a transport protocol that provides a 404 reliable ordered byte stream, an application could receive this byte 405 stream as partial Messages and transform it into application-layer 406 Messages. Alternatively, an application might provide a Message 407 Framer, which can transform a sequence of Messages into a byte stream 408 and vice versa (Section 9.1.2). 410 3.1.1. Server Example 412 This is an example of how an application might listen for incoming 413 Connections using the Transport Services API, and receive a request, 414 and send a response. 416 LocalSpecifier := NewLocalEndpoint() 417 LocalSpecifier.WithInterface("any") 418 LocalSpecifier.WithService("https") 420 TransportProperties := NewTransportProperties() 421 TransportProperties.Require(preserve-msg-boundaries) 422 // Reliable Data Transfer and Preserve Order are Required by default 424 SecurityParameters := NewSecurityParameters() 425 SecurityParameters.Set(identity, myIdentity) 426 SecurityParameters.Set(key-pair, myPrivateKey, myPublicKey) 428 // Specifying a Remote Endpoint is optional when using Listen() 429 Preconnection := NewPreconnection(LocalSpecifier, 430 TransportProperties, 431 SecurityParameters) 433 Listener := Preconnection.Listen() 435 Listener -> ConnectionReceived 437 // Only receive complete messages in a Conn.Received handler 438 Connection.Receive() 440 Connection -> Received 442 //---- Receive event handler begin ---- 443 Connection.Send(messageDataResponse) 444 Connection.Close() 446 // Stop listening for incoming Connections 447 // (this example supports only one Connection) 448 Listener.Stop() 449 //---- Receive event handler end ---- 451 3.1.2. Client Example 453 This is an example of how an application might open two Connections 454 to a remote application using the Transport Services API, and send a 455 request as well as receive a response on each of them. 457 RemoteSpecifier := NewRemoteEndpoint() 458 RemoteSpecifier.WithHostname("example.com") 459 RemoteSpecifier.WithService("https") 461 TransportProperties := NewTransportProperties() 462 TransportProperties.Require(preserve-msg-boundaries) 463 // Reliable Data Transfer and Preserve Order are Required by default 465 SecurityParameters := NewSecurityParameters() 466 TrustCallback := NewCallback({ 467 // Verify identity of the Remote Endpoint, return the result 468 }) 469 SecurityParameters.SetTrustVerificationCallback(TrustCallback) 471 // Specifying a local endpoint is optional when using Initiate() 472 Preconnection := NewPreconnection(RemoteSpecifier, 473 TransportProperties, 474 SecurityParameters) 476 Connection := Preconnection.Initiate() 477 Connection2 := Connection.Clone() 479 Connection -> Ready<> 480 Connection2 -> Ready<> 482 //---- Ready event handler for any Connection C begin ---- 483 C.Send(messageDataRequest) 485 // Only receive complete messages 486 C.Receive() 487 //---- Ready event handler for any Connection C end ---- 489 Connection -> Received 490 Connection2 -> Received 492 // Close the Connection in a Receive event handler 493 Connection.Close() 494 Connection2.Close() 496 Preconnections are reusable after being used to initiate a 497 Connection. Hence, for example, after the Connections were closed, 498 the following would be correct: 500 //.. carry out adjustments to the Preconnection, if desire 501 Connection := Preconnection.Initiate() 503 3.1.3. Peer Example 505 This is an example of how an application might establish a connection 506 with a peer using Rendezvous(), send a Message, and receive a 507 Message. 509 // Configure local candidates: a port on the Local Endpoint 510 // and via a STUN server 511 HostCandidate := NewLocalEndpoint() 512 HostCandidate.WithPort(9876) 514 StunCandidate := NewLocalEndpoint() 515 StunCandidate.WithStunServer(address, port, credentials) 517 LocalCandidates = [HostCandidate, StunCandidate] 519 // Configure transport and security properties 520 TransportProperties := ... 521 SecurityParameters := ... 523 Preconnection := NewPreconnection(LocalCandidates, 524 [], // No remote candidates yet 525 TransportProperties, 526 SecurityParameters) 528 // Resolve the LocalCandidates. The Preconnection.Resolve() call 529 // resolves both local and remote candidates but, since the remote 530 // candidates have not yet been specified, the ResolvedRemote list 531 // returned will be empty and is not used. 532 ResolvedLocal, ResolvedRemote = Preconnection.Resolve() 534 // ...Send the ResolvedLocal list to peer via signalling channel 535 // ...Receive a list of RemoteCandidates from peer via 536 // signalling channel 538 Preconnection.AddRemote(RemoteCandidates) 539 Preconnection.Rendezvous() 541 Preconnection -> RendezvousDone 543 //---- RendezvousDone event handler begin ---- 544 Connection.Send(messageDataRequest) 545 Connection.Receive() 546 //---- RendezvousDone event handler end ---- 548 Connection -> Received 550 // If new remote endpoint candidates are received from the peer over 551 // the signalling channel, for example if using Trickle ICE, then add 552 // them to the Connection: 553 Connection.AddRemote(NewRemoteCandidates) 555 // On a PathChange<> events, resolve the local endpoints to see if a 556 // new local endpoint has become available and, if so, send to the peer 557 // as a new candidate and add to the connection: 558 Connection -> PathChange<> 560 //---- PathChange event handler begin ---- 561 ResolvedLocal, ResolvedRemote = Preconnection.Resolve() 562 if ResolvedLocal has changed: 563 // ...Send the ResolvedLocal list to peer via signalling channel 564 // Add the new local endpoints to the connection: 565 Connection.AddLocal(ResolvedLocal) 566 //---- PathChange event handler end ---- 568 // Close the Connection in a Receive event handler 569 Connection.Close() 571 4. Transport Properties 573 Each application using the Transport Services API declares its 574 preferences for how the Transport Services system should operate. 575 This is done by using Transport Properties, as defined in 576 [I-D.ietf-taps-arch], at each stage of the lifetime of a connection. 578 Transport Properties are divided into Selection, Connection, and 579 Message Properties. Selection Properties (see Section 6.2) can only 580 be set during pre-establishment. They are only used to specify which 581 paths and protocol stacks can be used and are preferred by the 582 application. Although Connection Properties (see Section 8.1) can be 583 set during pre-establishment, they may be changed later. They are 584 used to inform decisions made during establishment and to fine-tune 585 the established connection. Calling Initiate on a Preconnection 586 creates an outbound Connection or a Listener, and the Selection 587 Properties remain readable from the Connection or Listener, but 588 become immutable. 590 The behavior of the selected protocol stack(s) when sending Messages 591 is controlled by Message Properties (see Section 9.1.3). 593 Selection Properties can be set on Preconnections, and the effect of 594 Selection Properties can be queried on Connections and Messages. 595 Connection Properties can be set on Connections and Preconnections; 596 when set on Preconnections, they act as an initial default for the 597 resulting Connections. Message Properties can be set on Messages, 598 Connections, and Preconnections; when set on the latter two, they act 599 as an initial default for the Messages sent over those Connections, 601 Note that configuring Connection Properties and Message Properties on 602 Preconnections is preferred over setting them later. Early 603 specification of Connection Properties allows their use as additional 604 input to the selection process. Protocol Specific Properties, which 605 enable configuration of specialized features of a specific protocol, 606 see Section 3.2 of [I-D.ietf-taps-arch], are not used as an input to 607 the selection process, but only support configuration if the 608 respective protocol has been selected. 610 4.1. Transport Property Names 612 Transport Properties are referred to by property names. For the 613 purposes of this document, these names are alphanumeric strings in 614 which words may be separated by hyphens. Specifically, the following 615 characters are allowed: lowercase letters a-z, uppercase letters A-Z, 616 digits 0-9, the hyphen -, and the underscore _. These names serve two 617 purposes: 619 * Allowing different components of a Transport Services 620 implementation to pass Transport Properties, e.g., between a 621 language frontend and a policy manager, or as a representation of 622 properties retrieved from a file or other storage. 624 * Making the code of different Transport Services implementations 625 look similar. While individual programming languages may preclude 626 strict adherence to the aforementioned naming convention (for 627 instance, by prohibiting the use of hyphens in symbols), users 628 interacting with multiple implementations will still benefit from 629 the consistency resulting from the use of visually similar 630 symbols. 632 Transport Property Names are hierarchically organized in the form 633 [.]. 635 * The Namespace component MUST be empty for well-known, generic 636 properties, i.e., for properties that are not specific to a 637 protocol and are defined in an RFC. 639 * Protocol Specific Properties MUST use the protocol acronym as the 640 Namespace, e.g., tcp for TCP specific Transport Properties. For 641 IETF protocols, property names under these namespaces SHOULD be 642 defined in an RFC. 644 * Vendor or implementation specific properties MUST use a string 645 identifying the vendor or implementation as the Namespace. 647 Namespaces for each of the keywords provided in the IANA protocol 648 numbers registry (see https://www.iana.org/assignments/protocol- 649 numbers/protocol-numbers.xhtml) are reserved for Protocol Specific 650 Properties and MUST NOT be used for vendor or implementation-specific 651 properties. Avoid using any of the terms listed as keywords in the 652 protocol numbers registry as any part of a vendor- or implementation- 653 specific property name. 655 4.2. Transport Property Types 657 Each Transport Property has a one of the basic types described in 658 Section 1.1. 660 Most Selection Properties (see Section 6.2) are of the Enumeration 661 type, and use the Preference Enumeration, which takes one of five 662 possible values (Prohibit, Avoid, Ignore, Prefer, or Require) 663 denoting the level of preference for a given property during protocol 664 selection. 666 5. Scope of the API Definition 668 This document defines a language- and platform-independent API of a 669 Transport Services system. Given the wide variety of languages and 670 language conventions used to write applications that use the 671 transport layer to connect to other applications over the Internet, 672 this independence makes this API necessarily abstract. 674 There is no interoperability benefit in tightly defining how the API 675 is presented to application programmers across diverse platforms. 676 However, maintaining the "shape" of the abstract API across different 677 platforms reduces the effort for programmers who learn to use the 678 Transport Services API to then apply their knowledge to another 679 platform. 681 We therefore make the following recommendations: 683 * Actions, Events, and Errors in implementations of the Transport 684 Services API SHOULD use the names given for them in the document, 685 subject to capitalization, punctuation, and other typographic 686 conventions in the language of the implementation, unless the 687 implementation itself uses different names for substantially 688 equivalent objects for networking by convention. 690 * Transport Services systems SHOULD implement each Selection 691 Property, Connection Property, and Message Context Property 692 specified in this document. The Transport Services API SHOULD be 693 implemented even when in a specific implementation/platform it 694 will always result in no operation, e.g. there is no action when 695 the API specifies a Property that is not available in a transport 696 protocol implemented on a specific platform. For example, if TCP 697 is the only underlying transport protocol, the Message Property 698 msgOrdered can be implemented (trivially, as a no-op) as disabling 699 the requirement for ordering will not have any effect on delivery 700 order for Connections over TCP. Similarly, the msg-lifetime 701 Message Property can be implemented but ignored, as the 702 description of this Property states that "it is not guaranteed 703 that a Message will not be sent when its Lifetime has expired". 705 * Implementations may use other representations for Transport 706 Property Names, e.g., by providing constants, but should provide a 707 straight-forward mapping between their representation and the 708 property names specified here. 710 6. Pre-Establishment Phase 712 The Pre-Establishment phase allows applications to specify properties 713 for the Connections that they are about to make, or to query the API 714 about potential Connections they could make. 716 A Preconnection Object represents a potential Connection. It is a 717 passive Object (a data structure) that merely maintains the state 718 that describes the properties of a Connection that might exist in the 719 future. This state comprises Local Endpoint and Remote Endpoint 720 Objects that denote the endpoints of the potential Connection (see 721 Section 6.1), the Selection Properties (see Section 6.2), any 722 preconfigured Connection Properties (Section 8.1), and the security 723 parameters (see Section 6.3): 725 Preconnection := NewPreconnection([]LocalEndpoint, 726 []RemoteEndpoint, 727 TransportProperties, 728 SecurityParameters) 730 At least one Local Endpoint MUST be specified if the Preconnection is 731 used to Listen() for incoming Connections, but the list of Local 732 Endpoints MAY be empty if the Preconnection is used to Initiate() 733 connections. If no Local Endpoint is specified, the Transport 734 Services system will assign an ephemeral local port to the Connection 735 on the appropriate interface(s). At least one Remote Endpoint MUST 736 be specified if the Preconnection is used to Initiate() Connections, 737 but the list of Remote Endpoints MAY be empty if the Preconnection is 738 used to Listen() for incoming Connections. At least one Local 739 Endpoint and one Remote Endpoint MUST be specified if a peer-to-peer 740 Rendezvous() is to occur based on the Preconnection. 742 If more than one Local Endpoint is specified on a Preconnection, then 743 all the Local Endpoints on the Preconnection MUST represent the same 744 host. For example, they might correspond to different interfaces on 745 a multi-homed host, of they might correspond to local interfaces and 746 a STUN server that can be resolved to a server reflexive address for 747 a Preconnection used to make a peer-to-peer Rendezvous(). 749 If more than one Remote Endpoint is specified on the Preconnection, 750 then all the Remote Endpoints on the Preconnection SHOULD represent 751 the same service. For example, the Remote Endpoints might represent 752 various network interfaces of a host, or a server reflexive address 753 that can be used to reach a host, or a set of hosts that provide 754 equivalent local balanced service. 756 In most cases, it is expected that a single Remote Endpoint will be 757 specified by name, and a later call to Initiate() on the 758 Preconnection (see Section 7.1) will internally resolve that name to 759 a list of concrete endpoints. Specifying multiple Remote Endpoints 760 on a Preconnection allows applications to override this for more 761 detailed control. 763 If Message Framers are used (see Section 9.1.2), they MUST be added 764 to the Preconnection during pre-establishment. 766 6.1. Specifying Endpoints 768 The transport services API uses the Local Endpoint and Remote 769 Endpoint Objects to refer to the endpoints of a transport connection. 770 Endpoints can be created as either Remote or Local: 772 RemoteSpecifier := NewRemoteEndpoint() 773 LocalSpecifier := NewLocalEndpoint() 774 A single Endpoint Object represents the identity of a network host. 775 That endpoint can be more or less specific depending on which 776 identifiers are set. For example, an Endpoint that only specifies a 777 hostname may in fact end up corresponding to several different IP 778 addresses on different hosts. 780 An Endpoint Object can be configured with the following identifiers: 782 * Hostname (string): 784 RemoteSpecifier.WithHostname("example.com") 786 * Port (a 16-bit integer): 788 RemoteSpecifier.WithPort(443) 790 * Service (an identifier that maps to a port; either a the name of a 791 well-known service, or a DNS SRV service name to be resolved): 793 RemoteSpecifier.WithService("https") 795 * IP address (IPv4 or IPv6 address): 797 RemoteSpecifier.WithIPv4Address(192.0.2.21) 799 RemoteSpecifier.WithIPv6Address(2001:db8:4920:e29d:a420:7461:7073:0a) 801 * Interface name (string), e.g., to qualify link-local or multicast 802 addresses (see Section 6.1.2 for details): 804 LocalSpecifier.WithInterface("en0") 806 Note that an IPv6 address specified with a scope (e.g. 807 2001:db8:4920:e29d:a420:7461:7073:0a%en0) is equivalent to 808 WithIPv6Address with an unscoped address and WithInterface together. 810 An Endpoint cannot have multiple identifiers of a same type set. 811 That is, an endpoint cannot have two IP addresses specified. Two 812 separate IP addresses are represented as two Endpoint Objects. If a 813 Preconnection specifies a Remote Endpoint with a specific IP address 814 set, it will only establish Connections to that IP address. If, on 815 the other hand, the Remote Endpoint specifies a hostname but no 816 addresses, the Connection can perform name resolution and attempt 817 using any address derived from the original hostname of the Remote 818 Endpoint. Note that multiple Remote Endpoints can be added to a 819 Preconnection, as discussed in Section 7.5. 821 The Transport Services system resolves names internally, when the 822 Initiate(), Listen(), or Rendezvous() method is called to establish a 823 Connection. Privacy considerations for the timing of this resolution 824 are given in Section 13. 826 The Resolve() action on a Preconnection can be used by the 827 application to force early binding when required, for example with 828 some Network Address Translator (NAT) traversal protocols (see 829 Section 7.3). 831 6.1.1. Using Multicast Endpoints 833 Specifying a multicast group address on a Local Endpoint will 834 indicate to the Transport Services system that the resulting 835 connection will be used to receive multicast messages. The Remote 836 Endpoint can be used to filter incoming multicast from specific 837 senders. Such a Preconnection will only support calling Listen(), 838 not Initiate(). Calling Listen() will cause the Transport Services 839 system to register for receiving multicast, such as issuing an IGMP 840 join [RFC3376] or using MLD for IPV6 [RFC4604]. Any Connections that 841 are accepted from this Listener are receive-only. 843 Similarly, specifying a multicast group address on the Remote 844 Endpoint will indicate that the resulting connection will be used to 845 send multicast messages, and that the Preconnection will support 846 Initiate() but not Listen(). Any Connections created this way are 847 send-only. 849 A Rendezvous() call on Preconnections containing group addresses 850 results in an EstablishmentError as described in Section 7.3. 852 See Section 6.1.5 for more examples. 854 6.1.2. Constraining Interfaces for Endpoints 856 Note that this API has multiple ways to constrain and prioritize 857 endpoint candidates based on the network interface: 859 * Specifying an interface on a RemoteEndpoint qualifies the scope of 860 the remote endpoint, e.g., for link-local addresses. 862 * Specifying an interface on a LocalEndpoint explicitly binds all 863 candidates derived from this endpoint to use the specified 864 interface. 866 * Specifying an interface using the interface Selection Property 867 (Section 6.2.11) or indirectly via the pvd Selection Property 868 (Section 6.2.12) influences the selection among the available 869 candidates. 871 While specifying an interface on an endpoint restricts the candidates 872 available for connection establishment in the Pre-Establishment 873 Phase, the Selection Properties prioritize and constrain the 874 connection establishment. 876 6.1.3. Endpoint Aliases 878 An Endpoint can have an alternative definition when using different 879 protocols. For example, a server that supports both TLS/TCP and QUIC 880 may be accessible on two different port numbers depending on which 881 protocol is used. 883 To support this, Endpoint Objects can specify "aliases". An Endpoint 884 can have multiple aliases set. 886 RemoteSpecifier.AddAlias(AlternateRemoteSpecifier) 888 In order to scope an alias to a specific transport protocol, an 889 Endpoint can specify a protocol identifier. 891 RemoteSpecifier.WithProtocol(QUIC) 893 The following example shows a case where "example.com" has a server 894 running on port 443, with an alternate port of 8443 for QUIC. 896 RemoteSpecifier := NewRemoteEndpoint() 897 RemoteSpecifier.WithHostname("example.com") 898 RemoteSpecifier.WithPort(443) 900 QUICRemoteSpecifier := NewRemoteEndpoint() 901 QUICRemoteSpecifier.WithHostname("example.com") 902 QUICRemoteSpecifier.WithPort(8443) 903 QUICRemoteSpecifier.WithProtocol(QUIC) 905 RemoteSpecifier.AddAlias(QUICRemoteSpecifier) 907 6.1.4. Endpoint Examples 909 The following examples of Endpoints show common usage patterns. 911 Specify a Remote Endpoint using a hostname and service name: 913 RemoteSpecifier := NewRemoteEndpoint() 914 RemoteSpecifier.WithHostname("example.com") 915 RemoteSpecifier.WithService("https") 917 Specify a Remote Endpoint using an IPv6 address and remote port: 919 RemoteSpecifier := NewRemoteEndpoint() 920 RemoteSpecifier.WithIPv6Address(2001:db8:4920:e29d:a420:7461:7073:0a) 921 RemoteSpecifier.WithPort(443) 923 Specify a Remote Endpoint using an IPv4 address and remote port: 925 RemoteSpecifier := NewRemoteEndpoint() 926 RemoteSpecifier.WithIPv4Address(192.0.2.21) 927 RemoteSpecifier.WithPort(443) 929 Specify a Local Endpoint using a local interface name and local port: 931 LocalSpecifier := NewLocalEndpoint() 932 LocalSpecifier.WithInterface("en0") 933 LocalSpecifier.WithPort(443) 935 As an alternative to specifying an interface name for the Local 936 Endpoint, an application can express more fine-grained preferences 937 using the Interface Instance or Type Selection Property, see 938 Section 6.2.11. However, if the application specifies Selection 939 Properties that are inconsistent with the Local Endpoint, this will 940 result in an Error once the application attempts to open a 941 Connection. 943 Specify a Local Endpoint using a STUN server: 945 LocalSpecifier := NewLocalEndpoint() 946 LocalSpecifier.WithStunServer(address, port, credentials) 948 6.1.5. Multicast Examples 950 Specify a Local Endpoint using an Any-Source Multicast group to join 951 on a named local interface: 953 LocalSpecifier := NewLocalEndpoint() 954 LocalSpecifier.WithIPv4Address(233.252.0.0) 955 LocalSpecifier.WithInterface("en0") 957 Source-Specific Multicast requires setting both a Local and Remote 958 Endpoint: 960 LocalSpecifier := NewLocalEndpoint() 961 LocalSpecifier.WithIPv4Address(232.1.1.1) 962 LocalSpecifier.WithInterface("en0") 964 RemoteSpecifier := NewRemoteEndpoint() 965 RemoteSpecifier.WithIPv4Address(192.0.2.22) 967 One common pattern for multicast is to both send and receive 968 multicast. For such cases, an application can set up both a Listener 969 and a Connection. The Listener is only used to accept Connections 970 that receive inbound multicast. The initiated Connection is only 971 used to send multicast. 973 // Prepare multicast Listener 974 LocalMulticastSpecifier := NewLocalEndpoint() 975 LocalMulticastSpecifier.WithIPv4Address(233.252.0.0) 976 LocalMulticastSpecifier.WithPort(5353) 977 LocalMulticastSpecifier.WithInterface("en0") 979 TransportProperties := NewTransportProperties() 980 TransportProperties.Require(preserve-msg-boundaries) 981 // Reliable Data Transfer and Preserve Order are Required by default 983 // Specifying a Remote Endpoint is optional when using Listen() 984 Preconnection := NewPreconnection(LocalMulticastSpecifier, 985 TransportProperties, 986 SecurityParameters) 988 MulticastListener := Preconnection.Listen() 990 // Handle inbound messages sent to the multicast group 991 MulticastListener -> ConnectionReceived 992 MulticastReceiverConnection.Receive() 993 MulticastReceiverConnection -> Received 995 // Prepare Connection to send multicast 996 LocalSpecifier := NewLocalEndpoint() 997 LocalSpecifier.WithPort(5353) 998 LocalSpecifier.WithInterface("en0") 999 RemoteMulticastSpecifier := NewRemoteEndpoint() 1000 RemoteMulticastSpecifier.WithIPv4Address(233.252.0.0) 1001 RemoteMulticastSpecifier.WithPort(5353) 1002 RemoteMulticastSpecifier.WithInterface("en0") 1004 Preconnection2 := NewPreconnection(LocalSpecifier, 1005 RemoteMulticastSpecifier, 1006 TransportProperties, 1007 SecurityParameters) 1009 // Send outbound messages to the multicast group 1010 MulticastSenderConnection := Preconnection.Initiate() 1011 MulticastSenderConnection.Send(messageData) 1013 6.2. Specifying Transport Properties 1015 A Preconnection Object holds properties reflecting the application's 1016 requirements and preferences for the transport. These include 1017 Selection Properties for selecting protocol stacks and paths, as well 1018 as Connection Properties and Message Properties for configuration of 1019 the detailed operation of the selected Protocol Stacks on a per- 1020 Connection and Message level. 1022 The protocol(s) and path(s) selected as candidates during 1023 establishment are determined and configured using these properties. 1024 Since there could be paths over which some transport protocols are 1025 unable to operate, or remote endpoints that support only specific 1026 network addresses or transports, transport protocol selection is 1027 necessarily tied to path selection. This may involve choosing 1028 between multiple local interfaces that are connected to different 1029 access networks. 1031 When additional information (such as Provisioning Domain (PvD) 1032 information [RFC7556]) is available about the networks over which an 1033 endpoint can operate, this can inform the selection between alternate 1034 network paths. 1035 Path information can include network segment PMTU, set of supported 1036 DSCPs, expected usage, cost, etc. The usage of this information by 1037 the Transport Services System is generally independent of the 1038 specific mechanism/protocol used to receive the information (e.g. 1039 zero-conf, DHCP, or IPv6 RA). 1041 Most Selection Properties are represented as Preferences, which can 1042 take one of five values: 1044 +============+========================================+ 1045 | Preference | Effect | 1046 +============+========================================+ 1047 | Require | Select only protocols/paths providing | 1048 | | the property, fail otherwise | 1049 +------------+----------------------------------------+ 1050 | Prefer | Prefer protocols/paths providing the | 1051 | | property, proceed otherwise | 1052 +------------+----------------------------------------+ 1053 | Ignore | No preference | 1054 +------------+----------------------------------------+ 1055 | Avoid | Prefer protocols/paths not providing | 1056 | | the property, proceed otherwise | 1057 +------------+----------------------------------------+ 1058 | Prohibit | Select only protocols/paths not | 1059 | | providing the property, fail otherwise | 1060 +------------+----------------------------------------+ 1062 Table 1: Selection Property Preference Levels 1064 The implementation MUST ensure an outcome that is consistent with all 1065 application requirements expressed using Require and Prohibit. While 1066 preferences expressed using Prefer and Avoid influence protocol and 1067 path selection as well, outcomes can vary given the same Selection 1068 Properties, because the available protocols and paths can differ 1069 across systems and contexts. However, implementations are 1070 RECOMMENDED to seek to provide a consistent outcome to an 1071 application, given the same set of Selection Properties. 1073 Note that application preferences can conflict with each other. For 1074 example, if an application indicates a preference for a specific path 1075 by specifying an interface, but also a preference for a protocol, a 1076 situation might occur in which the preferred protocol is not 1077 available on the preferred path. In such cases, applications can 1078 expect properties that determine path selection to be prioritized 1079 over properties that determine protocol selection. The transport 1080 system SHOULD determine the preferred path first, regardless of 1081 protocol preferences. This ordering is chosen to provide consistency 1082 across implementations, based on the fact that it is more common for 1083 the use of a given network path to determine cost to the user (i.e., 1084 an interface type preference might be based on a user's preference to 1085 avoid being charged more for a cellular data plan). 1087 Selection and Connection Properties, as well as defaults for Message 1088 Properties, can be added to a Preconnection to configure the 1089 selection process and to further configure the eventually selected 1090 protocol stack(s). They are collected into a TransportProperties 1091 object to be passed into a Preconnection object: 1093 TransportProperties := NewTransportProperties() 1095 Individual properties are then set on the TransportProperties Object. 1096 Setting a Transport Property to a value overrides the previous value 1097 of this Transport Property. 1099 TransportProperties.Set(property, value) 1101 To aid readability, implementations MAY provide additional 1102 convenience functions to simplify use of Selection Properties: see 1103 Appendix B.1 for examples. In addition, implementations MAY provide 1104 a mechanism to create TransportProperties objects that are 1105 preconfigured for common use cases as outlined in Appendix B.2. 1107 Transport Properties for an established connection can be queried via 1108 the Connection object, as outlined in Section 8. 1110 A Connection gets its Transport Properties either by being explicitly 1111 configured via a Preconnection, by configuration after establishment, 1112 or by inheriting them from an antecedent via cloning; see Section 7.4 1113 for more. 1115 Section 8.1 provides a list of Connection Properties, while Selection 1116 Properties are listed in the subsections below. Many properties are 1117 only considered during establishment, and can not be changed after a 1118 Connection is established; however, they can still be queried. The 1119 return type of a queried Selection Property is Boolean, where true 1120 means that the Selection Property has been applied and false means 1121 that the Selection Property has not been applied. Note that true 1122 does not mean that a request has been honored. For example, if 1123 Congestion control was requested with preference level Prefer, but 1124 congestion control could not be supported, querying the 1125 congestionControl property yields the value false. If the preference 1126 level Avoid was used for Congestion control, and, as requested, the 1127 Connection is not congestion controlled, querying the 1128 congestionControl property also yields the value false. 1130 An implementation of the Transport Services API must provide sensible 1131 defaults for Selection Properties. The default values for each 1132 property below represent a configuration that can be implemented over 1133 TCP. If these default values are used and TCP is not supported by a 1134 Transport Services system, then an application using the default set 1135 of Properties might not succeed in establishing a connection. Using 1136 the same default values for independent Transport Services 1137 implementations can be beneficial when applications are ported 1138 between different implementations/platforms, even if this default 1139 could lead to a connection failure when TCP is not available. If 1140 default values other than those suggested below are used, it is 1141 RECOMMENDED to clearly document any differences. 1143 6.2.1. Reliable Data Transfer (Connection) 1145 Name: reliability 1147 Type: Preference 1149 Default: Require 1151 This property specifies whether the application needs to use a 1152 transport protocol that ensures that all data is received at the 1153 Remote Endpoint without corruption. When reliable data transfer is 1154 enabled, this also entails being notified when a Connection is closed 1155 or aborted. 1157 6.2.2. Preservation of Message Boundaries 1159 Name: preserveMsgBoundaries 1161 Type: Preference 1163 Default: Ignore 1165 This property specifies whether the application needs or prefers to 1166 use a transport protocol that preserves message boundaries. 1168 6.2.3. Configure Per-Message Reliability 1170 Name: perMsgReliability 1172 Type: Preference 1174 Default: Ignore 1176 This property specifies whether an application considers it useful to 1177 specify different reliability requirements for individual Messages in 1178 a Connection. 1180 6.2.4. Preservation of Data Ordering 1182 Name: preserveOrder 1184 Type: Preference 1186 Default: Require 1188 This property specifies whether the application wishes to use a 1189 transport protocol that can ensure that data is received by the 1190 application on the other end in the same order as it was sent. 1192 6.2.5. Use 0-RTT Session Establishment with a Safely Replayable Message 1194 Name: zeroRttMsg 1196 Type: Preference 1198 Default: Ignore 1199 This property specifies whether an application would like to supply a 1200 Message to the transport protocol before Connection establishment 1201 that will then be reliably transferred to the other side before or 1202 during Connection establishment. This Message can potentially be 1203 received multiple times (i.e., multiple copies of the message data 1204 may be passed to the Remote Endpoint). See also Section 9.1.3.4. 1206 6.2.6. Multistream Connections in Group 1208 Name: multistreaming 1210 Type: Preference 1212 Default: Prefer 1214 This property specifies that the application would prefer multiple 1215 Connections within a Connection Group to be provided by streams of a 1216 single underlying transport connection where possible. 1218 6.2.7. Full Checksum Coverage on Sending 1220 Name: fullChecksumSend 1222 Type: Preference 1224 Default: Require 1226 This property specifies the application's need for protection against 1227 corruption for all data transmitted on this Connection. Disabling 1228 this property could enable later control of the sender checksum 1229 coverage (see Section 9.1.3.6). 1231 6.2.8. Full Checksum Coverage on Receiving 1233 Name: fullChecksumRecv 1235 Type: Preference 1237 Default: Require 1239 This property specifies the application's need for protection against 1240 corruption for all data received on this Connection. Disabling this 1241 property could enable later control of the required minimum receiver 1242 checksum coverage (see Section 8.1.1). 1244 6.2.9. Congestion control 1246 Name: congestionControl 1248 Type: Preference 1250 Default: Require 1252 This property specifies whether the application would like the 1253 Connection to be congestion controlled or not. Note that if a 1254 Connection is not congestion controlled, an application using such a 1255 Connection SHOULD itself perform congestion control in accordance 1256 with [RFC2914] or use a circuit breaker in accordance with [RFC8084], 1257 whichever is appropriate. Also note that reliability is usually 1258 combined with congestion control in protocol implementations, 1259 rendering "reliable but not congestion controlled" a request that is 1260 unlikely to succeed. If the Connection is congestion controlled, 1261 performing additional congestion control in the application can have 1262 negative performance implications. 1264 6.2.10. Keep alive 1266 Name: keepAlive 1268 Type: Preference 1270 Default: Ignore 1272 This property specifies whether the application would like the 1273 Connection to send keep-alive packets or not. Note that if a 1274 Connection determines that keep-alive packets are being sent, the 1275 applicaton should itself avoid generating additional keep alive 1276 messages. Note that when supported, the system will use the default 1277 period for generation of the keep alive-packets. (See also 1278 Section 8.1.4). 1280 6.2.11. Interface Instance or Type 1282 Name: interface 1284 Type: Collection of (Preference, Enumeration) 1286 Default: Empty (not setting a preference for any interface) 1287 This property allows the application to select any specific network 1288 interfaces or categories of interfaces it wants to Require, Prohibit, 1289 Prefer, or Avoid. Note that marking a specific interface as Require 1290 strictly limits path selection to that single interface, and often 1291 leads to less flexible and resilient connection establishment. 1293 In contrast to other Selection Properties, this property is a tuple 1294 of an (Enumerated) interface identifier and a preference, and can 1295 either be implemented directly as such, or for making one preference 1296 available for each interface and interface type available on the 1297 system. 1299 The set of valid interface types is implementation- and system- 1300 specific. For example, on a mobile device, there may be Wi-Fi and 1301 Cellular interface types available; whereas on a desktop computer, 1302 Wi-Fi and Wired Ethernet interface types might be available. An 1303 implementation should provide all types that are supported on the 1304 local system, to allow applications to be written generically. For 1305 example, if a single implementation is used on both mobile devices 1306 and desktop devices, it should define the Cellular interface type for 1307 both systems, since an application might wish to always prohibit 1308 cellular. 1310 The set of interface types is expected to change over time as new 1311 access technologies become available. The taxonomy of interface 1312 types on a given Transport Services system is implementation- 1313 specific. 1315 Interface types should not be treated as a proxy for properties of 1316 interfaces such as metered or unmetered network access. If an 1317 application needs to prohibit metered interfaces, this should be 1318 specified via Provisioning Domain attributes (see Section 6.2.12) or 1319 another specific property. 1321 Note that this property is not used to specify an interface scope for 1322 a particular endpoint. Section 6.1.2 provides details about how to 1323 qualify endpoint candidates on a per-interface basis. 1325 6.2.12. Provisioning Domain Instance or Type 1327 Name: pvd 1329 Type: Collection of (Preference, Enumeration) 1331 Default: Empty (not setting a preference for any PvD) 1332 Similar to interface instances and types (see Section 6.2.11), this 1333 property allows the application to control path selection by 1334 selecting which specific Provisioning Domain (PvD) or categories of 1335 PVDs it wants to Require, Prohibit, Prefer, or Avoid. Provisioning 1336 Domains define consistent sets of network properties that may be more 1337 specific than network interfaces [RFC7556]. 1339 As with interface instances and types, this property is a tuple of an 1340 (Enumerated) PvD identifier and a preference, and can either be 1341 implemented directly as such, or for making one preference available 1342 for each interface and interface type available on the system. 1344 The identification of a specific PvD is implementation- and system- 1345 specific, because there is currently no portable standard format for 1346 a PvD identifier. For example, this identifier might be a string 1347 name or an integer. As with requiring specific interfaces, requiring 1348 a specific PvD strictly limits the path selection. 1350 Categories or types of PvDs are also defined to be implementation- 1351 and system-specific. These can be useful to identify a service that 1352 is provided by a PvD. For example, if an application wants to use a 1353 PvD that provides a Voice-Over-IP service on a Cellular network, it 1354 can use the relevant PvD type to require a PvD that provides this 1355 service, without needing to look up a particular instance. While 1356 this does restrict path selection, it is broader than requiring 1357 specific PvD instances or interface instances, and should be 1358 preferred over these options. 1360 6.2.13. Use Temporary Local Address 1362 Name: useTemporaryLocalAddress 1364 Type: Preference 1366 Default: Avoid for Listeners and Rendezvous Connections. Prefer for 1367 other Connections. 1369 This property allows the application to express a preference for the 1370 use of temporary local addresses, sometimes called "privacy" 1371 addresses [RFC4941]. Temporary addresses are generally used to 1372 prevent linking connections over time when a stable address, 1373 sometimes called "permanent" address, is not needed. There are some 1374 caveats to note when specifying this property. First, if an 1375 application Requires the use of temporary addresses, the resulting 1376 Connection cannot use IPv4, because temporary addresses do not exist 1377 in IPv4. Second, temporary local addresses might involve trading off 1378 privacy for performance. For instance, temporary addresses can 1379 interfere with resumption mechanisms that some protocols rely on to 1380 reduce initial latency. 1382 6.2.14. Multipath Transport 1384 Name: multipath 1386 Type: Enumeration 1388 Default: Disabled for connections created through initiate and 1389 rendezvous, Passive for listeners 1391 This property specifies whether and how applications want to take 1392 advantage of transferring data across multiple paths between the same 1393 end hosts. Using multiple paths allows connections to migrate 1394 between interfaces or aggregate bandwidth as availability and 1395 performance properties change. Possible values are: 1397 Disabled: The connection will not use multiple paths once 1398 established, even if the chosen transport supports using multiple 1399 paths. 1401 Active: The connection will negotiate the use of multiple paths if 1402 the chosen transport supports this. 1404 Passive: The connection will support the use of multiple paths if 1405 the Remote Endpoint requests it. 1407 The policy for using multiple paths is specified using the separate 1408 multipath-policy property, see Section 8.1.7 below. To enable the 1409 peer endpoint to initiate additional paths towards a local address 1410 other than the one initially used, it is necessary to set the 1411 Alternative Addresses property (see Section 6.2.15 below). 1413 Setting this property to "Active", can have privacy implications: It 1414 enables the transport to establish connectivity using alternate paths 1415 that might result in users being linkable across the multiple paths, 1416 even if the Advertisement of Alternative Addresses property (see 1417 Section 6.2.15 below) is set to false. 1419 Note that Multipath Transport has no corresponding Selection Property 1420 of type Preference. Enumeration values other than "Disabled" are 1421 interpreted as a preference for choosing protocols that can make use 1422 of multiple paths. The "Disabled" value implies a requirement not to 1423 use multiple paths in parallel but does not prevent choosing a 1424 protocol that is capable of using multiple paths, e.g., it does not 1425 prevent choosing TCP, but prevents sending the MP_CAPABLE option in 1426 the TCP handshake. 1428 6.2.15. Advertisement of Alternative Addresses 1430 Name: advertises-altaddr 1432 Type: Boolean 1434 Default: False 1436 This property specifies whether alternative addresses, e.g., of other 1437 interfaces, should be advertised to the peer endpoint by the protocol 1438 stack. Advertising these addresses enables the peer-endpoint to 1439 establish additional connectivity, e.g., for connection migration or 1440 using multiple paths. 1442 Note that this can have privacy implications because it might result 1443 in users being linkable across the multiple paths. Also, note that 1444 setting this to false does not prevent the local Transport Services 1445 system from _establishing_ connectivity using alternate paths (see 1446 Section 6.2.14 above); it only prevents _proactive advertisement_ of 1447 addresses. 1449 6.2.16. Direction of communication 1451 Name: direction 1453 Type: Enumeration 1455 Default: Bidirectional 1457 This property specifies whether an application wants to use the 1458 connection for sending and/or receiving data. Possible values are: 1460 Bidirectional: The connection must support sending and receiving 1461 data 1463 Unidirectional send: The connection must support sending data, and 1464 the application cannot use the connection to receive any data 1466 Unidirectional receive: The connection must support receiving data, 1467 and the application cannot use the connection to send any data 1469 Since unidirectional communication can be supported by transports 1470 offering bidirectional communication, specifying unidirectional 1471 communication may cause a transport stack that supports bidirectional 1472 communication to be selected. 1474 6.2.17. Notification of ICMP soft error message arrival 1476 Name: softErrorNotify 1478 Type: Preference 1480 Default: Ignore 1482 This property specifies whether an application considers it useful to 1483 be informed when an ICMP error message arrives that does not force 1484 termination of a connection. When set to true, received ICMP errors 1485 are available as SoftErrors, see Section 8.3.1. Note that even if a 1486 protocol supporting this property is selected, not all ICMP errors 1487 will necessarily be delivered, so applications cannot rely upon 1488 receiving them [RFC8085]. 1490 6.2.18. Initiating side is not the first to write 1492 Name: activeReadBeforeSend 1494 Type: Preference 1496 Default: Ignore 1497 The most common client-server communication pattern involves the 1498 client actively opening a connection, then sending data to the 1499 server. The server listens (passive open), reads, and then answers. 1500 This property specifies whether an application wants to diverge from 1501 this pattern -- either by actively opening with Initiate(), 1502 immediately followed by reading, or passively opening with Listen(), 1503 immediately followed by writing. This property is ignored when 1504 establishing connections using Rendezvous(). Requiring this property 1505 limits the choice of mappings to underlying protocols, which can 1506 reduce efficiency. For example, it prevents the Transport Services 1507 system from mapping Connections to SCTP streams, where the first 1508 transmitted data takes the role of an active open signal 1509 [I-D.ietf-taps-impl]. 1511 6.3. Specifying Security Parameters and Callbacks 1513 Most security parameters, e.g., TLS ciphersuites, local identity and 1514 private key, etc., may be configured statically. Others are 1515 dynamically configured during connection establishment. Security 1516 parameters and callbacks are partitioned based on their place in the 1517 lifetime of connection establishment. Similar to Transport 1518 Properties, both parameters and callbacks are inherited during 1519 cloning (see Section 7.4). 1521 6.3.1. Specifying Security Parameters on a Pre-Connection 1523 Common security parameters such as TLS ciphersuites are known to 1524 implementations. Clients should use common safe defaults for these 1525 values whenever possible. However, as discussed in [RFC8922], many 1526 transport security protocols require specific security parameters and 1527 constraints from the client at the time of configuration and actively 1528 during a handshake. These configuration parameters need to be 1529 specified in the pre-connection phase and are created as follows: 1531 SecurityParameters := NewSecurityParameters() 1533 Security configuration parameters and sample usage follow: 1535 * Local identity and private keys: Used to perform private key 1536 operations and prove one's identity to the Remote Endpoint. 1537 (Note, if private keys are not available, e.g., since they are 1538 stored in hardware security modules (HSMs), handshake callbacks 1539 must be used. See below for details.) 1541 SecurityParameters.Set(identity, myIdentity) 1542 SecurityParameters.Set(key-pair, myPrivateKey, myPublicKey) 1543 * Supported algorithms: Used to restrict what parameters are used by 1544 underlying transport security protocols. When not specified, 1545 these algorithms should use known and safe defaults for the 1546 system. Parameters include: ciphersuites, supported groups, and 1547 signature algorithms. These parameters take a collection of 1548 supported algorithms as parameter. 1550 SecurityParameters.Set(supported-group, "secp256r1") 1551 SecurityParameters.Set(ciphersuite, "TLS_AES_128_GCM_SHA256") 1552 SecurityParameters.Set(signature-algorithm, "ecdsa_secp256r1_sha256") 1554 * Pre-Shared Key import: Used to install pre-shared keying material 1555 established out-of-band. Each pre-shared keying material is 1556 associated with some identity that typically identifies its use or 1557 has some protocol-specific meaning to the Remote Endpoint. 1559 SecurityParameters.Set(pre-shared-key, key, identity) 1561 * Session cache management: Used to tune session cache capacity, 1562 lifetime, and other policies. 1564 SecurityParameters.Set(max-cached-sessions, 16) 1565 SecurityParameters.Set(cached-session-lifetime-seconds, 3600) 1567 Connections that use Transport Services SHOULD use security in 1568 general. However, for compatibility with endpoints that do not 1569 support transport security protocols (such as a TCP endpoint that 1570 does not support TLS), applications can initialize their security 1571 parameters to indicate that security can be disabled, or can be 1572 opportunistic. If security is disabled, the Transport Services 1573 system will not attempt to add transport security automatically. If 1574 security is opportunistic, it will allow Connections without 1575 transport security, but will still attempt to use security if 1576 available. 1578 SecurityParameters := NewDisabledSecurityParameters() 1580 SecurityParameters := NewOpportunisticSecurityParameters() 1582 Representation of Security Parameters in implementations should 1583 parallel that chosen for Transport Property names as sugggested in 1584 Section 5. 1586 6.3.2. Connection Establishment Callbacks 1588 Security decisions, especially pertaining to trust, are not static. 1589 Once configured, parameters may also be supplied during connection 1590 establishment. These are best handled as client-provided callbacks. 1591 Callbacks block the progress of the connection establishment, which 1592 distinguishes them from other Events in the transport system. How 1593 callbacks and events are implemented is specific to each 1594 implementation. Security handshake callbacks that may be invoked 1595 during connection establishment include: 1597 * Trust verification callback: Invoked when a Remote Endpoint's 1598 trust must be validated before the handshake protocol can 1599 continue. 1601 TrustCallback := NewCallback({ 1602 // Handle trust, return the result 1603 }) 1604 SecurityParameters.SetTrustVerificationCallback(trustCallback) 1606 * Identity challenge callback: Invoked when a private key operation 1607 is required, e.g., when local authentication is requested by a 1608 Remote Endpoint. 1610 ChallengeCallback := NewCallback({ 1611 // Handle challenge 1612 }) 1613 SecurityParameters.SetIdentityChallengeCallback(challengeCallback) 1615 7. Establishing Connections 1617 Before a Connection can be used for data transfer, it needs to be 1618 established. Establishment ends the pre-establishment phase; all 1619 transport properties and cryptographic parameter specification must 1620 be complete before establishment, as these will be used to select 1621 candidate Paths and Protocol Stacks for the Connection. 1622 Establishment may be active, using the Initiate() Action; passive, 1623 using the Listen() Action; or simultaneous for peer-to-peer, using 1624 the Rendezvous() Action. These Actions are described in the 1625 subsections below. 1627 7.1. Active Open: Initiate 1629 Active open is the Action of establishing a Connection to a Remote 1630 Endpoint presumed to be listening for incoming Connection requests. 1631 Active open is used by clients in client-server interactions. Active 1632 open is supported by the Transport Services API through the Initiate 1633 Action: 1635 Connection := Preconnection.Initiate(timeout?) 1637 The timeout parameter specifies how long to wait before aborting 1638 Active open. Before calling Initiate, the caller must have populated 1639 a Preconnection Object with a Remote Endpoint specifier, optionally a 1640 Local Endpoint specifier (if not specified, the system will attempt 1641 to determine a suitable Local Endpoint), as well as all properties 1642 necessary for candidate selection. 1644 The Initiate() Action returns a Connection object. Once Initiate() 1645 has been called, any changes to the Preconnection MUST NOT have any 1646 effect on the Connection. However, the Preconnection can be reused, 1647 e.g., to Initiate another Connection. 1649 Once Initiate is called, the candidate Protocol Stack(s) may cause 1650 one or more candidate transport-layer connections to be created to 1651 the specified Remote Endpoint. The caller may immediately begin 1652 sending Messages on the Connection (see Section 9.2) after calling 1653 Initiate(); note that any data marked Safely Replayable that is sent 1654 while the Connection is being established may be sent multiple times 1655 or on multiple candidates. 1657 The following Events may be sent by the Connection after Initiate() 1658 is called: 1660 Connection -> Ready<> 1662 The Ready Event occurs after Initiate has established a transport- 1663 layer connection on at least one usable candidate Protocol Stack over 1664 at least one candidate Path. No Receive Events (see Section 9.3) 1665 will occur before the Ready Event for Connections established using 1666 Initiate. 1668 Connection -> EstablishmentError 1670 An EstablishmentError occurs either when the set of transport 1671 properties and security parameters cannot be fulfilled on a 1672 Connection for initiation (e.g., the set of available Paths and/or 1673 Protocol Stacks meeting the constraints is empty) or reconciled with 1674 the Local and/or Remote Endpoints; when the remote specifier cannot 1675 be resolved; or when no transport-layer connection can be established 1676 to the Remote Endpoint (e.g., because the Remote Endpoint is not 1677 accepting connections, the application is prohibited from opening a 1678 Connection by the operating system, or the establishment attempt has 1679 timed out for any other reason). 1681 Connection establishment and transmission of the first message can be 1682 combined in a single action Section 9.2.5. 1684 7.2. Passive Open: Listen 1686 Passive open is the Action of waiting for Connections from Remote 1687 Endpoints, commonly used by servers in client-server interactions. 1688 Passive open is supported by the Transport Services API through the 1689 Listen Action and returns a Listener object: 1691 Listener := Preconnection.Listen() 1693 Before calling Listen, the caller must have initialized the 1694 Preconnection during the pre-establishment phase with a Local 1695 Endpoint specifier, as well as all properties necessary for Protocol 1696 Stack selection. A Remote Endpoint may optionally be specified, to 1697 constrain what Connections are accepted. 1699 The Listen() Action returns a Listener object. Once Listen() has 1700 been called, any changes to the Preconnection MUST NOT have any 1701 effect on the Listener. The Preconnection can be disposed of or 1702 reused, e.g., to create another Listener. 1704 Listener.Stop() 1706 Listening continues until the global context shuts down, or until the 1707 Stop action is performed on the Listener object. 1709 Listener -> ConnectionReceived 1711 The ConnectionReceived Event occurs when a Remote Endpoint has 1712 established a transport-layer connection to this Listener (for 1713 Connection-oriented transport protocols), or when the first Message 1714 has been received from the Remote Endpoint (for Connectionless 1715 protocols), causing a new Connection to be created. The resulting 1716 Connection is contained within the ConnectionReceived Event, and is 1717 ready to use as soon as it is passed to the application via the 1718 event. 1720 Listener.SetNewConnectionLimit(value) 1722 If the caller wants to rate-limit the number of inbound Connections 1723 that will be delivered, it can set a cap using 1724 SetNewConnectionLimit(). This mechanism allows a server to protect 1725 itself from being drained of resources. Each time a new Connection 1726 is delivered by the ConnectionReceived Event, the value is 1727 automatically decremented. Once the value reaches zero, no further 1728 Connections will be delivered until the caller sets the limit to a 1729 higher value. By default, this value is Infinite. The caller is 1730 also able to reset the value to Infinite at any point. 1732 Listener -> EstablishmentError 1734 An EstablishmentError occurs either when the Properties and Security 1735 Parameters of the Preconnection cannot be fulfilled for listening or 1736 cannot be reconciled with the Local Endpoint (and/or Remote Endpoint, 1737 if specified), when the Local Endpoint (or Remote Endpoint, if 1738 specified) cannot be resolved, or when the application is prohibited 1739 from listening by policy. 1741 Listener -> Stopped<> 1743 A Stopped Event occurs after the Listener has stopped listening. 1745 7.3. Peer-to-Peer Establishment: Rendezvous 1747 Simultaneous peer-to-peer Connection establishment is supported by 1748 the Rendezvous() Action: 1750 Preconnection.Rendezvous() 1752 A Preconnection Object used in a Rendezvous() MUST have both the 1753 Local Endpoint candidates and the Remote Endpoint candidates 1754 specified, along with the transport properties and security 1755 parameters needed for Protocol Stack selection, before the 1756 Rendezvous() Action is initiated. 1758 The Rendezvous() Action listens on the Local Endpoint candidates for 1759 an incoming Connection from the Remote Endpoint candidates, while 1760 also simultaneously trying to establish a Connection from the Local 1761 Endpoint candidates to the Remote Endpoint candidates. 1763 If there are multiple Local Endpoints or Remote Endpoints configured, 1764 then initiating a Rendezvous() action will systematically probe the 1765 reachability of those endpoint candidates following an approach such 1766 as that used in Interactive Connectivity Establishment (ICE) 1767 [RFC5245]. 1769 If the endpoints are suspected to be behind a NAT, Rendezvous() can 1770 be initiated using Local Endpoints that support a method of 1771 discovering NAT bindings such as Session Traversal Utilities for NAT 1772 (STUN) [RFC8489] or Traversal Using Relays around NAT (TURN) 1773 [RFC5766]. In this case, the Local Endpoint will resolve to a 1774 mixture of local and server reflexive addresses. The Resolve() 1775 action on the Preconnection can be used to discover these bindings: 1777 []LocalEndpoint, []RemoteEndpoint := Preconnection.Resolve() 1778 The Resolve() call returns lists of Local Endpoints and Remote 1779 Endpoints, that represent the concrete addresses, local and server 1780 reflexive, on which a Rendezvous() for the Preconnection will listen 1781 for incoming Connections, and to which it will attempt to establish 1782 connections. 1784 Note that the set of LocalEndpoints returned by Resolve() might or 1785 might not contain information about all possible local interfaces; it 1786 is valid only for a Rendezvous happening at the same time as the 1787 resolution. Care should be taken in using these values in any other 1788 context. 1790 An application that uses Rendezvous() to establish a peer-to-peer 1791 connection in the presence of NATs will configure the Preconnection 1792 object with at least one a Local Endpoint that supports NAT binding 1793 discovery. It will then Resolve() the Preconnection, and pass the 1794 resulting list of Local Endpoint candidates to the peer via a 1795 signalling protocol, for example as part of an ICE [RFC5245] exchange 1796 within SIP [RFC3261] or WebRTC [RFC7478]. The peer will then, via 1797 the same signalling channel, return the Remote Endpoint candidates. 1798 The set of Remote Endpoint candidates are then configured onto the 1799 Preconnection: 1801 Preconnection.AddRemote([]RemoteEndpoint) 1803 The Rendezvous() Action can be initiated once both the Local Endpoint 1804 candidates and the Remote Endpoint candidates retrieved from the peer 1805 via the signalling channel have been added to the Preconnection. 1807 If successful, the Rendezvous() Action returns a Connection object 1808 via a RendezvousDone<> Event: 1810 Preconnection -> RendezvousDone 1812 The RendezvousDone<> Event occurs when a Connection is established 1813 with the Remote Endpoint. For Connection-oriented transports, this 1814 occurs when the transport-layer connection is established; for 1815 Connectionless transports, it occurs when the first Message is 1816 received from the Remote Endpoint. The resulting Connection is 1817 contained within the RendezvousDone<> Event, and is ready to use as 1818 soon as it is passed to the application via the Event. Changes made 1819 to a Preconnection after Rendezvous() has been called do not have any 1820 effect on existing Connections. 1822 An EstablishmentError occurs either when the Properties and Security 1823 Parameters of the Preconnection cannot be fulfilled for rendezvous or 1824 cannot be reconciled with the Local and/or Remote Endpoints, when the 1825 Local Endpoint or Remote Endpoint cannot be resolved, when no 1826 transport-layer connection can be established to the Remote Endpoint, 1827 or when the application is prohibited from rendezvous by policy: 1829 Preconnection -> EstablishmentError 1831 7.4. Connection Groups 1833 Connection Groups can be created using the Clone Action: 1835 Connection := Connection.Clone(framer?) 1837 Calling Clone on a Connection yields a Connection Group containing 1838 two Connections: the parent Connection on which Clone was called, and 1839 a resulting cloned Connection. The new Connection is actively 1840 openend, and it will send a Ready Event or an EstablishmentError 1841 Event. Calling Clone on any of these Connections adds another 1842 Connection to the Connection Group. Connections in a Connection 1843 Group share all Connection Properties except Connection Priority (see 1844 Section 8.1.2), and these Connection Properties are entangled: 1845 Changing one of the Connection Properties on one Connection in the 1846 Connection Group automatically changes the Connection Property for 1847 all others. For example, changing Timeout for aborting Connection 1848 (see Section 8.1.3) on one Connection in a Connection Group will 1849 automatically make the same change to this Connection Property for 1850 all other Connections in the Connection Group. Like all other 1851 Properties, Connection Priority is copied to the new Connection when 1852 calling Clone(), but in this case, a later change to the Connection 1853 Priority on one Connection does not change it on the other 1854 Connections in the same Connection Group. 1856 Message Properties set on a Connection also apply only to that 1857 Connection. 1859 A new Connection created by Clone can have a Message Framer assigned 1860 via the optional framer parameter of the Clone Action. If this 1861 parameter is not supplied, the stack of Message Framers associated 1862 with a Connection is copied to the cloned Connection when calling 1863 Clone. Then, a cloned Connection has the same stack of Message 1864 Framers as the Connection from which they are Cloned, but these 1865 Framers may internally maintain per-Connection state. 1867 It is also possible to check which Connections belong to the same 1868 Connection Group. Calling GroupedConnections() on a specific 1869 Connection returns a set of all Connections in the same group. 1871 []Connection := Connection.GroupedConnections() 1873 Connections will belong to the same group if the application 1874 previously called Clone. Passive Connections can also be added to 1875 the same group -- e.g., when a Listener receives a new Connection 1876 that is just a new stream of an already active multi-streaming 1877 protocol instance. 1879 If the underlying protocol supports multi-streaming, it is natural to 1880 use this functionality to implement Clone. In that case, Connections 1881 in a Connection Group are multiplexed together, giving them similar 1882 treatment not only inside endpoints, but also across the end-to-end 1883 Internet path. 1885 Note that calling Clone() can result in on-the-wire signaling, e.g., 1886 to open a new transport connection, depending on the underlying 1887 Protocol Stack. When Clone() leads to the opening of multiple such 1888 connections, the Transport Services system will ensure consistency of 1889 Connection Properties by uniformly applying them to all underlying 1890 connections in a group. Even in such a case, there are possibilities 1891 for a Transport Services system to implement prioritization within a 1892 Connection Group [TCP-COUPLING] [RFC8699]. 1894 Attempts to clone a Connection can result in a CloneError: 1896 Connection -> CloneError 1898 The Connection Priority Connection Property operates on Connections 1899 in a Connection Group using the same approach as in Section 9.1.3.2: 1900 when allocating available network capacity among Connections in a 1901 Connection Group, sends on Connections with higher Priority values 1902 will be prioritized over sends on Connections that have lower 1903 Priority values. Capacity will be shared among these Connections 1904 according to the Connection Group Transmission Scheduler property 1905 (Section 8.1.5). See Section 9.2.6 for more. 1907 7.5. Adding and Removing Endpoints on a Connection 1909 Transport protocols that are explicitly multipath aware are expected 1910 to automatically manage the set of Remote Endpoints that they are 1911 communicating with, and the paths to those endpoints. A PathChange<> 1912 event, described in Section 8.3.2, will be generated when the path 1913 changes. 1915 In some cases, however, it is necessary to explicitly indicate to a 1916 Connection that a new remote endpoint has become available for use, 1917 or to indicate that some remote endpoint is no longer available. 1918 This is most common in the case of peer to peer connections using 1919 Trickle ICE [RFC8838]. 1921 The AddRemote() action can be used to add one or more new remote 1922 endpoints to a Connection: 1924 Connection.AddRemote([]RemoteEndpoint) 1926 Endpoints that are already known to the Connection are ignored. A 1927 call to AddRemote() makes the new remote endpoints available to the 1928 connection, but whether the Connection makes use of those endpoints 1929 will depend on the underlying transport protocol. 1931 Similarly, the RemoveRemote() action can be used to tell a connection 1932 to stop using one or more remote endpoints: 1934 Connection.RemoveRemote([]RemoteEndpoint) 1936 Removing all known remote endpoints can have the effect of aborting 1937 the connection. The effect of removing the active remote endpoint(s) 1938 depends on the underlying transport: multipath aware transports might 1939 be able to switch to a new path if other reachable remote endpoints 1940 exist, or the connection might abort. 1942 Similarly, the AddLocal() and RemoveLocal() actions can be used to 1943 add and remove local endpoints to/from a Connection. 1945 8. Managing Connections 1947 During pre-establishment and after establishment, connections can be 1948 configured and queried using Connection Properties, and asynchronous 1949 information may be available about the state of the connection via 1950 Soft Errors. 1952 Connection Properties represent the configuration and state of the 1953 selected Protocol Stack(s) backing a Connection. These Connection 1954 Properties may be Generic, applying regardless of transport protocol, 1955 or Specific, applicable to a single implementation of a single 1956 transport protocol stack. Generic Connection Properties are defined 1957 in Section 8.1 below. 1959 Protocol Specific Properties are defined in a transport- and 1960 implementation-specific way to permit more specialized protocol 1961 features to be used. Too much reliance by an application on Protocol 1962 Specific Properties can significantly reduce the flexibility of a 1963 transport services implementation to make appropriate selection and 1964 configuration choices. Therefore, it is RECOMMENDED that Protocol 1965 Properties are used for properties common across different protocols 1966 and that Protocol Specific Properties are only used where specific 1967 protocols or properties are necessary. 1969 The application can set and query Connection Properties on a per- 1970 Connection basis. Connection Properties that are not read-only can 1971 be set during pre-establishment (see Section 6.2), as well as on 1972 connections directly using the SetProperty action: 1974 Connection.SetProperty(property, value) 1976 Note that changing one of the Connection Properties on one Connection 1977 in a Connection Group will also change it for all other Connections 1978 of that group; see further Section 7.4. 1980 At any point, the application can query Connection Properties. 1982 ConnectionProperties := Connection.GetProperties() 1983 value := ConnectionProperties.Get(property) 1984 if ConnectionProperties.Has(boolean_or_preference_property) then ... 1986 Depending on the status of the connection, the queried Connection 1987 Properties will include different information: 1989 * The connection state, which can be one of the following: 1990 Establishing, Established, Closing, or Closed. 1992 * Whether the connection can be used to send data. A connection can 1993 not be used for sending if the connection was created with the 1994 Selection Property Direction of Communication set to 1995 unidirectional receive or if a Message marked as Final was sent 1996 over this connection. See also Section 9.1.3.5. 1998 * Whether the connection can be used to receive data. A connection 1999 cannot be used for reading if the connection was created with the 2000 Selection Property Direction of Communication set to 2001 unidirectional send or if a Message marked as Final was received. 2002 See Section 9.3.3.3. The latter is only supported by certain 2003 transport protocols, e.g., by TCP as half-closed connection. 2005 * For Connections that are Established, Closing, or Closed: 2006 Connection Properties (Section 8.1) of the actual protocols that 2007 were selected and instantiated, and Selection Properties that the 2008 application specified on the Preconnection. Selection Properties 2009 of type Preference will be exposed as boolean values indicating 2010 whether or not the property applies to the selected transport. 2012 Note that the instantiated protocol stack might not match all 2013 Protocol Selection Properties that the application specified on 2014 the Preconnection. 2016 * For Connections that are Established: information concerning the 2017 path(s) used by the Protocol Stack. This can be derived from 2018 local PVD information, measurements by the Protocol Stack, or 2019 other sources. For example, a TAPS system that is configured to 2020 receive and process PVD information [RFC7556] could also provide 2021 network configuration information for the chosen path(s). 2023 8.1. Generic Connection Properties 2025 Generic Connection Properties are defined independent of the chosen 2026 protocol stack and therefore available on all Connections. 2028 Many Connection Properties have a corresponding Selection Property 2029 that enables applications to express their preference for protocols 2030 providing a supporting transport feature. 2032 8.1.1. Required Minimum Corruption Protection Coverage for Receiving 2034 Name: recvChecksumLen 2036 Type: Integer or Full Coverage 2038 Default: Full Coverage 2040 If this property is an Integer, it specifies the minimum number of 2041 bytes in a received message that need to be covered by a checksum. A 2042 receiving endpoint will not forward messages that have less coverage 2043 to the application. The application is responsible for handling any 2044 corruption within the non-protected part of the message [RFC8085]. A 2045 special value of 0 means that a received packet may also have a zero 2046 checksum field. 2048 8.1.2. Connection Priority 2050 Name: connPriority 2052 Type: Integer (non-negative) 2054 Default: 100 2056 This Property is a non-negative integer representing the priority of 2057 this Connection relative to other Connections in the same Connection 2058 Group. A higher value reflects a higher priority. It has no effect 2059 on Connections not part of a Connection Group. As noted in 2060 Section 7.4, this property is not entangled when Connections are 2061 cloned, i.e., changing the Priority on one Connection in a Connection 2062 Group does not change it on the other Connections in the same 2063 Connection Group. No guarantees of a specific behavior regarding 2064 Connection Priority are given; a Transport Services system may ignore 2065 this property. See Section 9.2.6 for more details. 2067 8.1.3. Timeout for Aborting Connection 2069 Name: connTimeout 2071 Type: Numeric or Disabled 2073 Default: Disabled 2075 If this property is Numeric, it specifies how long to wait before 2076 deciding that an active Connection has failed when trying to reliably 2077 deliver data to the Remote Endpoint. Adjusting this Property will 2078 only take effect when the underlying stack supports reliability. If 2079 this property has the enumerated value Disabled, it means that no 2080 timeout is scheduled. 2082 8.1.4. Timeout for keep alive packets 2084 Name: keepAliveTimeout 2086 Type: Numeric or Disabled 2088 Default: Implementation-defined 2090 A Transport Services API can request a protocol that supports sending 2091 keep alive packets Section 6.2.10. If this property is an Integer, 2092 it specifies the maximum length of time an idle connection (one for 2093 which no transport packets have been sent) should wait before the 2094 Local Endpoint sends a keep-alive packet to the Remote Endpoint. 2095 Adjusting this Property will only take effect when the underlying 2096 stack supports sending keep-alive packets. Guidance on setting this 2097 value for datagram transports is provided in [RFC8085]. A value 2098 greater than the connection timeout (Section 8.1.3) or the enumerated 2099 value Disabled will disable the sending of keep-alive packets. 2101 8.1.5. Connection Group Transmission Scheduler 2103 Name: connScheduler 2105 Type: Enumeration 2107 Default: Weighted Fair Queueing (see Section 3.6 in [RFC8260]) 2108 This property specifies which scheduler should be used among 2109 Connections within a Connection Group, see Section 7.4. The set of 2110 schedulers can be taken from [RFC8260]. 2112 8.1.6. Capacity Profile 2114 Name: connCapacityProfile 2116 Type: Enumeration 2118 Default: Default Profile (Best Effort) 2120 This property specifies the desired network treatment for traffic 2121 sent by the application and the tradeoffs the application is prepared 2122 to make in path and protocol selection to receive that desired 2123 treatment. When the capacity profile is set to a value other than 2124 Default, z Transport Services system SHOULD select paths and 2125 configure protocols to optimize the tradeoff between delay, delay 2126 variation, and efficient use of the available capacity based on the 2127 capacity profile specified. How this is realized is implementation- 2128 specific. The Capacity Profile MAY also be used to set markings on 2129 the wire for Protocol Stacks supporting this. Recommendations for 2130 use with DSCP are provided below for each profile; note that when a 2131 Connection is multiplexed, the guidelines in Section 6 of [RFC7657] 2132 apply. 2134 The following values are valid for the Capacity Profile: 2136 Default: The application provides no information about its expected 2137 capacity profile. Transport Services implementations that map the 2138 requested capacity profile onto per-connection DSCP signaling 2139 SHOULD assign the DSCP Default Forwarding [RFC2474] Per Hop 2140 Behaviour (PHB). 2142 Scavenger: The application is not interactive. It expects to send 2143 and/or receive data without any urgency. This can, for example, 2144 be used to select protocol stacks with scavenger transmission 2145 control and/or to assign the traffic to a lower-effort service. 2146 Transport Services implementations that map the requested capacity 2147 profile onto per-connection DSCP signaling SHOULD assign the DSCP 2148 Less than Best Effort [RFC8622] PHB. 2150 Low Latency/Interactive: The application is interactive, and prefers 2151 loss to latency. Response time should be optimized at the expense 2152 of delay variation and efficient use of the available capacity 2153 when sending on this connection. This can be used by the system 2154 to disable the coalescing of multiple small Messages into larger 2155 packets (Nagle's algorithm); to prefer immediate acknowledgment 2156 from the peer endpoint when supported by the underlying transport; 2157 and so on. Transport Services implementations that map the 2158 requested capacity profile onto per-connection DSCP signaling 2159 without multiplexing SHOULD assign a DSCP Assured Forwarding 2160 (AF41,AF42,AF43,AF44) [RFC2597] PHB. Inelastic traffic that is 2161 expected to conform to the configured network service rate could 2162 be mapped to the DSCP Expedited Forwarding [RFC3246] or [RFC5865] 2163 PHBs. 2165 Low Latency/Non-Interactive: The application prefers loss to 2166 latency, but is not interactive. Response time should be 2167 optimized at the expense of delay variation and efficient use of 2168 the available capacity when sending on this connection. Transport 2169 system implementations that map the requested capacity profile 2170 onto per-connection DSCP signaling without multiplexing SHOULD 2171 assign a DSCP Assured Forwarding (AF21,AF22,AF23,AF24) [RFC2597] 2172 PHB. 2174 Constant-Rate Streaming: The application expects to send/receive 2175 data at a constant rate after Connection establishment. Delay and 2176 delay variation should be minimized at the expense of efficient 2177 use of the available capacity. This implies that the Connection 2178 might fail if the Path is unable to maintain the desired rate. A 2179 transport can interpret this capacity profile as preferring a 2180 circuit breaker [RFC8084] to a rate-adaptive congestion 2181 controller. Transport system implementations that map the 2182 requested capacity profile onto per-connection DSCP signaling 2183 without multiplexing SHOULD assign a DSCP Assured Forwarding 2184 (AF31,AF32,AF33,AF34) [RFC2597] PHB. 2186 Capacity-Seeking: The application expects to send/receive data at 2187 the maximum rate allowed by its congestion controller over a 2188 relatively long period of time. Transport Services 2189 implementations that map the requested capacity profile onto per- 2190 connection DSCP signaling without multiplexing SHOULD assign a 2191 DSCP Assured Forwarding (AF11,AF12,AF13,AF14) [RFC2597] PHB per 2192 Section 4.8 of [RFC4594]. 2194 The Capacity Profile for a selected protocol stack may be modified on 2195 a per-Message basis using the Transmission Profile Message Property; 2196 see Section 9.1.3.8. 2198 8.1.7. Policy for using Multipath Transports 2200 Name: multipath-policy 2202 Type: Enumeration 2203 Default: Handover 2205 This property specifies the local policy for transferring data across 2206 multiple paths between the same end hosts if Multipath Transport is 2207 not set to Disabled (see Section 6.2.14). Possible values are: 2209 Handover: The connection ought only to attempt to migrate between 2210 different paths when the original path is lost or becomes 2211 unusable. The thresholds used to declare a path unusable are 2212 implementation specific. 2214 Interactive: The connection ought only to attempt to minimize the 2215 latency for interactive traffic patterns by transmitting data 2216 across multiple paths when this is beneficial. The goal of 2217 minimizing the latency will be balanced against the cost of each 2218 of these paths. Depending on the cost of the lower-latency path, 2219 the scheduling might choose to use a higher-latency path. Traffic 2220 can be scheduled such that data may be transmitted on multiple 2221 paths in parallel to achieve a lower latency. The specific 2222 scheduling algorithm is implementation-specific. 2224 Aggregate: The connection ought to attempt to use multiple paths in 2225 parallel to maximize available capacity and possibly overcome the 2226 capacity limitations of the individual paths. The actual strategy 2227 is implementation specific. 2229 Note that this is a local choice - the Remote Endpoint can choose a 2230 different policy. 2232 8.1.8. Bounds on Send or Receive Rate 2234 Name: minSendRate / minRecvRate / maxSendRate / maxRecvRate 2236 Type: Numeric or Unlimited / Numeric or Unlimited / Numeric or 2237 Unlimited / Numeric or Unlimited 2239 Default: Unlimited / Unlimited / Unlimited / Unlimited 2241 Integer values of this property specify an upper-bound rate that a 2242 transfer is not expected to exceed (even if flow control and 2243 congestion control allow higher rates), and/or a lower-bound rate 2244 below which the application does not deem it will be useful. These 2245 are specified in bits per second. The enumerated value Unlimited 2246 indicates that no bound is specified. 2248 8.1.9. Group Connection Limit 2250 Name: groupConnLimit 2252 Type: Numeric or Unlimited 2254 Default: Unlimited 2256 If this property is an Integer, it controls the number of Connections 2257 that can be accepted from a peer as new members of the Connection's 2258 group. Similar to SetNewConnectionLimit(), this limits the number of 2259 ConnectionReceived Events that will occur, but constrained to the 2260 group of the Connection associated with this property. For a multi- 2261 streaming transport, this limits the number of allowed streams. 2263 8.1.10. Isolate Session 2265 Name: isolateSession 2267 Type: Boolean 2269 Default: false 2271 When set to true, this property will initiate new Connections using 2272 as little cached information (such as session tickets or cookies) as 2273 possible from previous connections that are not in the same 2274 Connection Group. Any state generated by this Connection will only 2275 be shared with Connections in the same Connection Group. Cloned 2276 Connections will use saved state from within the Connection Group. 2277 This is used for separating Connection Contexts as specified in 2278 [I-D.ietf-taps-arch]. 2280 Note that this does not guarantee no leakage of information, as 2281 implementations may not be able to fully isolate all caches (e.g. 2282 RTT estimates). Note that this property may degrade connection 2283 performance. 2285 8.1.11. Read-only Connection Properties 2287 The following generic Connection Properties are read-only, i.e. they 2288 cannot be changed by an application. 2290 8.1.11.1. Maximum Message Size Concurrent with Connection Establishment 2292 Name: zeroRttMsgMaxLen 2294 Type: Integer 2295 This property represents the maximum Message size that can be sent 2296 before or during Connection establishment, see also Section 9.1.3.4. 2297 It is given in Bytes. 2299 8.1.11.2. Maximum Message Size Before Fragmentation or Segmentation 2301 Name: singularTransmissionMsgMaxLen 2303 Type: Integer 2305 This property, if applicable, represents the maximum Message size 2306 that can be sent without incurring network-layer fragmentation at the 2307 sender. It exposes a value to the application based on the Maximum 2308 Packet Size (MPS) as described in Datagram PLPMTUD [RFC8899]. This 2309 can allow a sending stack to avoid unwanted fragmentation at the 2310 network-layer or segmentation by the transport layer. 2312 8.1.11.3. Maximum Message Size on Send 2314 Name: sendMsgMaxLen 2316 Type: Integer 2318 This property represents the maximum Message size that an application 2319 can send. 2321 8.1.11.4. Maximum Message Size on Receive 2323 Name: recvMsgMaxLen 2325 Type: Integer 2327 This numeric property represents the maximum Message size that an 2328 application can receive. 2330 8.2. TCP-specific Properties: User Timeout Option (UTO) 2332 These properties specify configurations for the User Timeout Option 2333 (UTO), in the case that TCP becomes the chosen transport protocol. 2334 Implementation is optional and useful only if TCP is implemented in 2335 the Transport Services system. 2337 These TCP-specific properties are included here because the feature 2338 Suggest timeout to the peer is part of the minimal set of transport 2339 services [RFC8923], where this feature was categorized as 2340 "functional". This means that when an Transport Services 2341 implementation offers this feature, the Transport Services API has to 2342 expose an interface to the application. Otherwise, the 2343 implementation might violate assumptions by the application, which 2344 could cause the application to fail. 2346 All of the below properties are optional (e.g., it is possible to 2347 specify User Timeout Enabled as true, but not specify an Advertised 2348 User Timeout value; in this case, the TCP default will be used). 2349 These properties reflect the API extension specified in Section 3 of 2350 [RFC5482]. 2352 8.2.1. Advertised User Timeout 2354 Name: tcp.userTimeoutValue 2356 Type: Integer 2358 Default: the TCP default 2360 This time value is advertised via the TCP User Timeout Option (UTO) 2361 [RFC5482] at the Remote Endpoint to adapt its own Timeout for 2362 aborting Connection (see Section 8.1.3) value. 2364 8.2.2. User Timeout Enabled 2366 Name: tcp.userTimeoutEnabled 2368 Type: Boolean 2370 Default: false 2372 This property controls whether the UTO option is enabled for a 2373 connection. This applies to both sending and receiving. 2375 8.2.3. Timeout Changeable 2377 Name: tcp.userTimeoutChangeable 2379 Type: Boolean 2381 Default: true 2382 This property controls whether the Timeout for aborting Connection 2383 (see Section 8.1.3) may be changed based on a UTO option received 2384 from the remote peer. This boolean becomes false when Timeout for 2385 aborting Connection (see Section 8.1.3) is used. 2387 8.3. Connection Lifecycle Events 2389 During the lifetime of a connection there are events that can occur 2390 when configured. 2392 8.3.1. Soft Errors 2394 Asynchronous introspection is also possible, via the SoftError Event. 2395 This event informs the application about the receipt and contents of 2396 an ICMP error message related to the Connection. This will only 2397 happen if the underlying protocol stack supports access to soft 2398 errors; however, even if the underlying stack supports it, there is 2399 no guarantee that a soft error will be signaled. 2401 Connection -> SoftError<> 2403 8.3.2. Path change 2405 This event notifies the application when at least one of the paths 2406 underlying a Connection has changed. Changes occur on a single path 2407 when the PMTU changes as well as when multiple paths are used and 2408 paths are added or removed, the set of local endpoints changes, or a 2409 handover has been performed. 2411 Connection -> PathChange<> 2413 9. Data Transfer 2415 Data is sent and received as Messages, which allows the application 2416 to communicate the boundaries of the data being transferred. 2418 9.1. Messages and Framers 2420 Each Message has an optional Message Context, which allows to add 2421 Message Properties, identify Send Events related to a specific 2422 Message or to inspect meta-data related to the Message sent. Framers 2423 can be used to extend or modify the message data with additional 2424 information that can be processed at the receiver to detect message 2425 boundaries. 2427 9.1.1. Message Contexts 2429 Using the MessageContext object, the application can set and retrieve 2430 meta-data of the message, including Message Properties (see 2431 Section 9.1.3) and framing meta-data (see Section 9.1.2.2). 2432 Therefore, a MessageContext object can be passed to the Send action 2433 and is returned by each Send and Receive related event. 2435 Message Properties can be set and queried using the Message Context: 2437 MessageContext.add(scope?, parameter, value) 2438 PropertyValue := MessageContext.get(scope?, property) 2440 To get or set Message Properties, the optional scope parameter is 2441 left empty. To get or set meta-data for a Framer, the application 2442 has to pass a reference to this Framer as the scope parameter. 2444 For MessageContexts returned by send Events (see Section 9.2.2) and 2445 receive Events (see Section 9.3.2), the application can query 2446 information about the Local and Remote Endpoint: 2448 RemoteEndpoint := MessageContext.GetRemoteEndpoint() 2449 LocalEndpoint := MessageContext.GetLocalEndpoint() 2451 9.1.2. Message Framers 2453 Although most applications communicate over a network using well- 2454 formed Messages, the boundaries and metadata of the Messages are 2455 often not directly communicated by the transport protocol itself. 2456 For example, HTTP applications send and receive HTTP messages over a 2457 byte-stream transport, requiring that the boundaries of HTTP messages 2458 be parsed from the stream of bytes. 2460 Message Framers allow extending a Connection's Protocol Stack to 2461 define how to encapsulate or encode outbound Messages, and how to 2462 decapsulate or decode inbound data into Messages. Message Framers 2463 allow message boundaries to be preserved when using a Connection 2464 object, even when using byte-stream transports. This is designed 2465 based on the fact that many of the current application protocols 2466 evolved over TCP, which does not provide message boundary 2467 preservation, and since many of these protocols require message 2468 boundaries to function, each application layer protocol has defined 2469 its own framing. 2471 To use a Message Framer, the application adds it to its Preconnection 2472 object. Then, the Message Framer can intercept all calls to Send() 2473 or Receive() on a Connection to add Message semantics, in addition to 2474 interacting with the setup and teardown of the Connection. A Framer 2475 can start sending data before the application sends data if the 2476 framing protocol requires a prefix or handshake (see [RFC8229] for an 2477 example of such a framing protocol). 2479 Initiate() Send() Receive() Close() 2480 | | ^ | 2481 | | | | 2482 +----v----------v---------+----------v-----+ 2483 | Connection | 2484 +----+----------+---------^----------+-----+ 2485 | | | | 2486 | +-----------------+ | 2487 | | Messages | | 2488 | +-----------------+ | 2489 | | | | 2490 +----v----------v---------+----------v-----+ 2491 | Framer(s) | 2492 +----+----------+---------^----------+-----+ 2493 | | | | 2494 | +-----------------+ | 2495 | | Byte-stream | | 2496 | +-----------------+ | 2497 | | | | 2498 +----v----------v---------+----------v-----+ 2499 | Transport Protocol Stack | 2500 +------------------------------------------+ 2502 Figure 1: Protocol Stack showing a Message Framer 2504 Note that while Message Framers add the most value when placed above 2505 a protocol that otherwise does not preserve message boundaries, they 2506 can also be used with datagram- or message-based protocols. In these 2507 cases, they add an additional transformation to further encode or 2508 encapsulate, and can potentially support packing multiple 2509 application-layer Messages into individual transport datagrams. 2511 The API to implement a Message Framer can vary depending on the 2512 implementation; guidance on implementing Message Framers can be found 2513 in [I-D.ietf-taps-impl]. 2515 9.1.2.1. Adding Message Framers to Pre-Connections 2517 The Message Framer object can be added to one or more Preconnections 2518 to run on top of transport protocols. Multiple Framers may be added 2519 to a Preconnection; in this case, the Framers operate as a framing 2520 stack, i.e. the last one added runs first when framing outbound 2521 messages, and last when parsing inbound data. 2523 The following example adds a basic HTTP Message Framer to a 2524 Preconnection: 2526 framer := NewHTTPMessageFramer() 2527 Preconnection.AddFramer(framer) 2529 Since Message Framers pass from Preconnection to Listener or 2530 Connection, addition of Framers must happen before any operation that 2531 may result in the creation of a Connection. 2533 9.1.2.2. Framing Meta-Data 2535 When sending Messages, applications can add Framer-specific key/value 2536 pairs to a MessageContext (Section 9.1.1). This mechanism can be 2537 used, for example, to set the type of a Message for a TLV format. 2538 The namespace of values is custom for each unique Message Framer. 2540 messageContext := NewMessageContext() 2541 messageContext.add(framer, key, value) 2542 Connection.Send(messageData, messageContext) 2544 When an application receives a MessageContext in a Receive event, it 2545 can also look to see if a value was set by a specific Message Framer. 2547 messageContext.get(framer, key) -> value 2549 For example, if an HTTP Message Framer is used, the values could 2550 correspond to HTTP headers: 2552 httpFramer := NewHTTPMessageFramer() 2553 ... 2554 messageContext := NewMessageContext() 2555 messageContext.add(httpFramer, "accept", "text/html") 2557 9.1.3. Message Properties 2559 Applications needing to annotate the Messages they send with extra 2560 information (for example, to control how data is scheduled and 2561 processed by the transport protocols supporting the Connection) can 2562 include this information in the Message Context passed to the Send 2563 Action. For other uses of the message context, see Section 9.1.1. 2565 Message Properties are per-Message, not per-Send if partial Messages 2566 are sent (Section 9.2.3). All data blocks associated with a single 2567 Message share properties specified in the Message Contexts. For 2568 example, it would not make sense to have the beginning of a Message 2569 expire, but allow the end of a Message to still be sent. 2571 A MessageContext object contains metadata for the Messages to be sent 2572 or received. 2574 messageData := "hello" 2575 messageContext := NewMessageContext() 2576 messageContext.add(parameter, value) 2577 Connection.Send(messageData, messageContext) 2579 The simpler form of Send, which does not take any messageContext, is 2580 equivalent to passing a default MessageContext without adding any 2581 Message Properties. 2583 If an application wants to override Message Properties for a specific 2584 message, it can acquire an empty MessageContext Object and add all 2585 desired Message Properties to that Object. It can then reuse the 2586 same messageContext Object for sending multiple Messages with the 2587 same properties. 2589 Properties can be added to a MessageContext object only before the 2590 context is used for sending. Once a MessageContext has been used 2591 with a Send call, further modifications to the MessageContext object 2592 do not have any effect on this Send call. 2594 The Message Properties could be inconsistent with the properties of 2595 the Protocol Stacks underlying the Connection on which a given 2596 Message is sent. For example, a Protocol Stack must be able to 2597 provide ordering if the msgOrdered property of a Message is enabled. 2598 Sending a Message with Message Properties inconsistent with the 2599 Selection Properties of the Connection yields an error. 2601 If a Message Property contradicts a Connection Property, and if this 2602 per-Message behavior can be supported, it overrides the Connection 2603 Property for the specific Message. For example, if Reliable Data 2604 Transfer (Connection) is set to Require and a protocol with 2605 configurable per-Message reliability is used, setting Reliable Data 2606 Transfer (Message) to false for a particular Message will allow this 2607 Message to be sent without any reliability guarantees. Changing the 2608 Reliable Data Transfer property on Messages is only possible for 2609 Connections that were established enabling the Selection Property 2610 Configure Per-Message Reliability. 2612 The following Message Properties are supported: 2614 9.1.3.1. Lifetime 2616 Name: msgLifetime 2618 Type: Numeric 2619 Default: infinite 2621 The Lifetime specifies how long a particular Message can wait to be 2622 sent to the Remote Endpoint before it is irrelevant and no longer 2623 needs to be (re-)transmitted. This is a hint to the Transport 2624 Services implementation -- it is not guaranteed that a Message will 2625 not be sent when its Lifetime has expired. 2627 Setting a Message's Lifetime to infinite indicates that the 2628 application does not wish to apply a time constraint on the 2629 transmission of the Message, but it does not express a need for 2630 reliable delivery; reliability is adjustable per Message via the 2631 Reliable Data Transfer (Message) property (see Section 9.1.3.7). The 2632 type and units of Lifetime are implementation-specific. 2634 9.1.3.2. Priority 2636 Name: msgPriority 2638 Type: Integer (non-negative) 2640 Default: 100 2642 This property specifies the priority of a Message, relative to other 2643 Messages sent over the same Connection. 2645 A Message with Priority 0 will yield to a Message with Priority 1, 2646 which will yield to a Message with Priority 2, and so on. Priorities 2647 may be used as a sender-side scheduling construct only, or be used to 2648 specify priorities on the wire for Protocol Stacks supporting 2649 prioritization. 2651 Note that this property is not a per-message override of the 2652 Connection Priority - see Section 8.1.2. The Priority properties may 2653 interact, but can be used independently and be realized by different 2654 mechanisms; see Section 9.2.6. 2656 9.1.3.3. Ordered 2658 Name: msgOrdered 2660 Type: Boolean 2662 Default: the queried Boolean value of the Selection Property 2663 preserveOrder (Section 6.2.4) 2665 The order in which Messages were submitted for transmission via the 2666 Send Action will be preserved on delivery via Receive<> events for 2667 all Messages on a Connection that have this Message Property set to 2668 true. 2670 If false, the Message is delivered to the receiving application 2671 without preserving the ordering. This property is used for protocols 2672 that support preservation of data ordering, see Section 6.2.4, but 2673 allow out-of-order delivery for certain messages, e.g., by 2674 multiplexing independent messages onto different streams. 2676 9.1.3.4. Safely Replayable 2678 Name: safelyReplayable 2680 Type: Boolean 2682 Default: false 2684 If true, Safely Replayable specifies that a Message is safe to send 2685 to the Remote Endpoint more than once for a single Send Action. It 2686 marks the data as safe for certain 0-RTT establishment techniques, 2687 where retransmission of the 0-RTT data may cause the remote 2688 application to receive the Message multiple times. 2690 For protocols that do not protect against duplicated messages, e.g., 2691 UDP, all messages need to be marked as Safely Replayable. To enable 2692 protocol selection to choose such a protocol, Safely Replayable needs 2693 to be added to the TransportProperties passed to the Preconnection. 2694 If such a protocol was chosen, disabling Safely Replayable on 2695 individual messages MUST result in a SendError. 2697 9.1.3.5. Final 2699 Name: final 2701 Type: Boolean 2703 Default: false 2705 If true, this indicates a Message is the last that the application 2706 will send on a Connection. This allows underlying protocols to 2707 indicate to the Remote Endpoint that the Connection has been 2708 effectively closed in the sending direction. For example, TCP-based 2709 Connections can send a FIN once a Message marked as Final has been 2710 completely sent, indicated by marking endOfMessage. Protocols that 2711 do not support signalling the end of a Connection in a given 2712 direction will ignore this property. 2714 A Final Message must always be sorted to the end of a list of 2715 Messages. The Final property overrides Priority and any other 2716 property that would re-order Messages. If another Message is sent 2717 after a Message marked as Final has already been sent on a 2718 Connection, the Send Action for the new Message will cause a 2719 SendError Event. 2721 9.1.3.6. Sending Corruption Protection Length 2723 Name: msgChecksumLen 2725 Type: Integer or Full Coverage 2727 Default: Full Coverage 2729 If this property is an Integer, it specifies the minimum length of 2730 the section of a sent Message, starting from byte 0, that the 2731 application requires to be delivered without corruption due to lower 2732 layer errors. It is used to specify options for simple integrity 2733 protection via checksums. A value of 0 means that no checksum needs 2734 to be calculated, and the enumerated value Full Coverage means that 2735 the entire Message needs to be protected by a checksum. Only Full 2736 Coverage is guaranteed, any other requests are advisory, which may 2737 result in Full Coverage being applied. 2739 9.1.3.7. Reliable Data Transfer (Message) 2741 Name: msgReliable 2743 Type: Boolean 2745 Default: the queried Boolean value of the Selection Property 2746 reliability (Section 6.2.1) 2748 When true, this property specifies that a Message should be sent in 2749 such a way that the transport protocol ensures all data is received 2750 on the other side without corruption. Changing the Reliable Data 2751 Transfer property on Messages is only possible for Connections that 2752 were established enabling the Selection Property Configure Per- 2753 Message Reliability. When this is not the case, changing msgReliable 2754 will generate an error. 2756 Disabling this property indicates that the Transport Services system 2757 may disable retransmissions or other reliability mechanisms for this 2758 particular Message, but such disabling is not guaranteed. 2760 9.1.3.8. Message Capacity Profile Override 2762 Name: msgCapacityProfile 2764 Type: Enumeration 2766 Default: inherited from the Connection Property connCapacityProfile 2767 (Section 8.1.6) 2769 This enumerated property specifies the application's preferred 2770 tradeoffs for sending this Message; it is a per-Message override of 2771 the Capacity Profile connection property (see Section 8.1.6). 2773 9.1.3.9. No Network-Layer Fragmentation 2775 Name: noFragmentation 2777 Type: Boolean 2779 Default: false 2781 This property specifies that a message should be sent and received 2782 without network-layer fragmentation, if possible. It can be used to 2783 avoid network layer fragmentation when transport segmentation is 2784 prefered. 2786 This only takes effect when the transport uses a network layer that 2787 supports this functionality. When it does take effect, setting this 2788 property to true will cause the sender to avoid network-layer source 2789 frgementation. When using IPv4, this will result in the Don't 2790 Fragment bit being set in the IP header. 2792 Attempts to send a message with this property that result in a size 2793 greater than the transport's current estimate of its maximum packet 2794 size (singularTransmissionMsgMaxLen) can result in transport 2795 segmentation when permitted, or in a SendError. 2797 Note: noSegmentation should be used when it is desired to only send a 2798 message within a single network packet. 2800 9.1.3.10. No Segmentation 2802 Name: noSegmentation 2804 Type: Boolean 2806 Default: false 2807 When set to true, this property requests the transport layer to not 2808 provide segmentation of messages larger than the maximum size 2809 permitted by the network layer, and also to avoid network-layer 2810 source fragmentation of messages. When running over IPv4, setting 2811 this property to true can result in a sending endpount setting the 2812 Don't Fragment bit in the IPv4 header of packets generated by the 2813 transport layer. An attempt to send a message that results in a size 2814 greater than the transport's current estimate of its maximum packet 2815 size (singularTransmissionMsgMaxLen) will result in a SendError. 2816 This only takes effect when the transport and network layer support 2817 this functionality. 2819 9.2. Sending Data 2821 Once a Connection has been established, it can be used for sending 2822 Messages. By default, Send enqueues a complete Message, and takes 2823 optional per-Message properties (see Section 9.2.1). All Send 2824 actions are asynchronous, and deliver Events (see Section 9.2.2). 2825 Sending partial Messages for streaming large data is also supported 2826 (see Section 9.2.3). 2828 Messages are sent on a Connection using the Send action: 2830 Connection.Send(messageData, messageContext?, endOfMessage?) 2832 where messageData is the data object to send, and messageContext 2833 allows adding Message Properties, identifying Send Events related to 2834 a specific Message or inspecting meta-data related to the Message 2835 sent (see Section 9.1.1). 2837 The optional endOfMessage parameter supports partial sending and is 2838 described in Section 9.2.3. 2840 9.2.1. Basic Sending 2842 The most basic form of sending on a connection involves enqueuing a 2843 single Data block as a complete Message with default Message 2844 Properties. 2846 messageData := "hello" 2847 Connection.Send(messageData) 2849 The interpretation of a Message to be sent is dependent on the 2850 implementation, and on the constraints on the Protocol Stacks implied 2851 by the Connection's transport properties. For example, a Message may 2852 be a single datagram for UDP Connections; or an HTTP Request for HTTP 2853 Connections. 2855 Some transport protocols can deliver arbitrarily sized Messages, but 2856 other protocols constrain the maximum Message size. Applications can 2857 query the Connection Property "Maximum Message size on send" 2858 (Section 8.1.11.3) to determine the maximum size allowed for a single 2859 Message. If a Message is too large to fit in the Maximum Message 2860 Size for the Connection, the Send will fail with a SendError event 2861 (Section 9.2.2.3). For example, it is invalid to send a Message over 2862 a UDP connection that is larger than the available datagram sending 2863 size. 2865 9.2.2. Send Events 2867 Like all Actions in Transport Services API, the Send Action is 2868 asynchronous. There are several Events that can be delivered in 2869 response to Sending a Message. Exactly one Event (Sent, Expired, or 2870 SendError) will be delivered in response to each call to Send. 2872 Note that if partial Sends are used (Section 9.2.3), there will still 2873 be exactly one Send Event delivered for each call to Send. For 2874 example, if a Message expired while two requests to Send data for 2875 that Message are outstanding, there will be two Expired events 2876 delivered. 2878 The Transport Services API should allow the application to correlate 2879 which Send Action resulted in a particular Send Event. The manner in 2880 which this correlation is indicated is implementation-specific. 2882 9.2.2.1. Sent 2884 Connection -> Sent 2886 The Sent Event occurs when a previous Send Action has completed, 2887 i.e., when the data derived from the Message has been passed down or 2888 through the underlying Protocol Stack and is no longer the 2889 responsibility of the Transport Services API. The exact disposition 2890 of the Message (i.e., whether it has actually been transmitted, moved 2891 into a buffer on the network interface, moved into a kernel buffer, 2892 and so on) when the Sent Event occurs is implementation-specific. 2893 The Sent Event contains a reference to the Message Context of the 2894 Message to which it applies. 2896 Sent Events allow an application to obtain an understanding of the 2897 amount of buffering it creates. That is, if an application calls the 2898 Send Action multiple times without waiting for a Sent Event, it has 2899 created more buffer inside the Transport Services system than an 2900 application that always waits for the Sent Event before calling the 2901 next Send Action. 2903 9.2.2.2. Expired 2905 Connection -> Expired 2907 The Expired Event occurs when a previous Send Action expired before 2908 completion; i.e. when the Message was not sent before its Lifetime 2909 (see Section 9.1.3.1) expired. This is separate from SendError, as 2910 it is an expected behavior for partially reliable transports. The 2911 Expired Event contains a reference to the Message Context of the 2912 Message to which it applies. 2914 9.2.2.3. SendError 2916 Connection -> SendError 2918 A SendError occurs when a Message was not sent due to an error 2919 condition: an attempt to send a Message which is too large for the 2920 system and Protocol Stack to handle, some failure of the underlying 2921 Protocol Stack, or a set of Message Properties not consistent with 2922 the Connection's transport properties. The SendError contains a 2923 reference to the Message Context of the Message to which it applies. 2925 9.2.3. Partial Sends 2927 It is not always possible for an application to send all data 2928 associated with a Message in a single Send Action. The Message data 2929 may be too large for the application to hold in memory at one time, 2930 or the length of the Message may be unknown or unbounded. 2932 Partial Message sending is supported by passing an endOfMessage 2933 boolean parameter to the Send Action. This value is always true by 2934 default, and the simpler forms of Send are equivalent to passing true 2935 for endOfMessage. 2937 The following example sends a Message in two separate calls to Send. 2939 messageContext := NewMessageContext() 2940 messageContext.add(parameter, value) 2942 messageData := "hel" 2943 endOfMessage := false 2944 Connection.Send(messageData, messageContext, endOfMessage) 2946 messageData := "lo" 2947 endOfMessage := true 2948 Connection.Send(messageData, messageContext, endOfMessage) 2949 All data sent with the same MessageContext object will be treated as 2950 belonging to the same Message, and will constitute an in-order series 2951 until the endOfMessage is marked. 2953 9.2.4. Batching Sends 2955 To reduce the overhead of sending multiple small Messages on a 2956 Connection, the application could batch several Send Actions 2957 together. This provides a hint to the system that the sending of 2958 these Messages ought to be coalesced when possible, and that sending 2959 any of the batched Messages can be delayed until the last Message in 2960 the batch is enqueued. 2962 The semantics for starting and ending a batch can be implementation- 2963 specific, but need to allow multiple Send Actions to be enqueued. 2965 Connection.StartBatch() 2966 Connection.Send(messageData) 2967 Connection.Send(messageData) 2968 Connection.EndBatch() 2970 9.2.5. Send on Active Open: InitiateWithSend 2972 For application-layer protocols where the Connection initiator also 2973 sends the first message, the InitiateWithSend() action combines 2974 Connection initiation with a first Message sent: 2976 Connection := Preconnection.InitiateWithSend(messageData, messageContext?, timeout?) 2978 Whenever possible, a messageContext should be provided to declare the 2979 Message passed to InitiateWithSend as Safely Replayable. This allows 2980 the Transport Services system to make use of 0-RTT establishment in 2981 case this is supported by the available protocol stacks. When the 2982 selected stack(s) do not support transmitting data upon connection 2983 establishment, InitiateWithSend is identical to Initiate() followed 2984 by Send(). 2986 Neither partial sends nor send batching are supported by 2987 InitiateWithSend(). 2989 The Events that may be sent after InitiateWithSend() are equivalent 2990 to those that would be sent by an invocation of Initiate() followed 2991 immediately by an invocation of Send(), with the caveat that a send 2992 failure that occurs because the Connection could not be established 2993 will not result in a SendError separate from the EstablishmentError 2994 signaling the failure of Connection establishment. 2996 9.2.6. Priority and the Transport Services API 2998 The Transport Services API provides two properties to allow a sender 2999 to signal the relative priority of data transmission: the Priority 3000 Message Property Section 9.1.3.2, and the Connection Priority 3001 Connection Property Section 8.1.2. These properties are designed to 3002 allow the expression and implementation of a wide variety of 3003 approaches to transmission priority in the transport and application 3004 layer, including those which do not appear on the wire (affecting 3005 only sender-side transmission scheduling) as well as those that do 3006 (e.g. [I-D.ietf-httpbis-priority]. 3008 A Transport Services system gives no guarantees about how its 3009 expression of relative priorities will be realized. However, the 3010 Transport Services system will seek to ensure that performance of 3011 relatively-prioritized connections and messages is not worse with 3012 respect to those connections and messages than an equivalent 3013 configuration in which all prioritization properties are left at 3014 their defaults. 3016 The Transport Services API does order Connection Priority over the 3017 Priority Message Property. In the absense of other externalities 3018 (e.g., transport-layer flow control), a priority 1 Message on a 3019 priority 0 Connection will be sent before a priority 0 Message on a 3020 priority 1 Connection in the same group. 3022 9.3. Receiving Data 3024 Once a Connection is established, it can be used for receiving data 3025 (unless the Direction of Communication property is set to 3026 unidirectional send). As with sending, the data is received in 3027 Messages. Receiving is an asynchronous operation, in which each call 3028 to Receive enqueues a request to receive new data from the 3029 connection. Once data has been received, or an error is encountered, 3030 an event will be delivered to complete any pending Receive requests 3031 (see Section 9.3.2). If Messages arrive at the Transport Services 3032 system before Receive requests are issued, ensuing Receive requests 3033 will first operate on these Messages before awaiting any further 3034 Messages. 3036 9.3.1. Enqueuing Receives 3038 Receive takes two parameters to specify the length of data that an 3039 application is willing to receive, both of which are optional and 3040 have default values if not specified. 3042 Connection.Receive(minIncompleteLength?, maxLength?) 3043 By default, Receive will try to deliver complete Messages in a single 3044 event (Section 9.3.2.1). 3046 The application can set a minIncompleteLength value to indicate the 3047 smallest partial Message data size in bytes that should be delivered 3048 in response to this Receive. By default, this value is infinite, 3049 which means that only complete Messages should be delivered (see 3050 Section 9.3.2.2 and Section 9.1.2 for more information on how this is 3051 accomplished). If this value is set to some smaller value, the 3052 associated receive event will be triggered only when at least that 3053 many bytes are available, or the Message is complete with fewer 3054 bytes, or the system needs to free up memory. Applications should 3055 always check the length of the data delivered to the receive event 3056 and not assume it will be as long as minIncompleteLength in the case 3057 of shorter complete Messages or memory issues. 3059 The maxLength argument indicates the maximum size of a Message in 3060 bytes that the application is currently prepared to receive. The 3061 default value for maxLength is infinite. If an incoming Message is 3062 larger than the minimum of this size and the maximum Message size on 3063 receive for the Connection's Protocol Stack, it will be delivered via 3064 ReceivedPartial events (Section 9.3.2.2). 3066 Note that maxLength does not guarantee that the application will 3067 receive that many bytes if they are available; the Transport Services 3068 API could return ReceivedPartial events with less data than maxLength 3069 according to implementation constraints. Note also that maxLength 3070 and minIncompleteLength are intended only to manage buffering, and 3071 are not interpreted as a receiver preference for message reordering. 3073 9.3.2. Receive Events 3075 Each call to Receive will be paired with a single Receive Event, 3076 which can be a success or an error. This allows an application to 3077 provide backpressure to the transport stack when it is temporarily 3078 not ready to receive messages. 3080 The Transport Services API should allow the application to correlate 3081 which call to Receive resulted in a particular Receive Event. The 3082 manner in which this correlation is indicated is implementation- 3083 specific. 3085 9.3.2.1. Received 3087 Connection -> Received 3088 A Received event indicates the delivery of a complete Message. It 3089 contains two objects, the received bytes as messageData, and the 3090 metadata and properties of the received Message as messageContext. 3092 The messageData object provides access to the bytes that were 3093 received for this Message, along with the length of the byte array. 3094 The messageContext is provided to enable retrieving metadata about 3095 the message and referring to the message. The messageContext object 3096 ist described in Section 9.1.1. 3098 See Section 9.1.2 for handling Message framing in situations where 3099 the Protocol Stack only provides a byte-stream transport. 3101 9.3.2.2. ReceivedPartial 3103 Connection -> ReceivedPartial 3105 If a complete Message cannot be delivered in one event, one part of 3106 the Message can be delivered with a ReceivedPartial event. To 3107 continue to receive more of the same Message, the application must 3108 invoke Receive again. 3110 Multiple invocations of ReceivedPartial deliver data for the same 3111 Message by passing the same MessageContext, until the endOfMessage 3112 flag is delivered or a ReceiveError occurs. All partial blocks of a 3113 single Message are delivered in order without gaps. This event does 3114 not support delivering discontiguous partial Messages. If, for 3115 example, Message A is divided into three pieces (A1, A2, A3) and 3116 Message B is divided into three pieces (B1, B2, B3), and 3117 preserveOrder is not Required, the ReceivedPartial may deliver them 3118 in a sequence like this: A1, B1, B2, A2, A3, B3, because the 3119 messageContext allows the application to identify the pieces as 3120 belonging to Message A and B, respectively. However, a sequence 3121 like: A1, A3 will never occur. 3123 If the minIncompleteLength in the Receive request was set to be 3124 infinite (indicating a request to receive only complete Messages), 3125 the ReceivedPartial event may still be delivered if one of the 3126 following conditions is true: 3128 * the underlying Protocol Stack supports message boundary 3129 preservation, and the size of the Message is larger than the 3130 buffers available for a single message; 3132 * the underlying Protocol Stack does not support message boundary 3133 preservation, and the Message Framer (see Section 9.1.2) cannot 3134 determine the end of the message using the buffer space it has 3135 available; or 3137 * the underlying Protocol Stack does not support message boundary 3138 preservation, and no Message Framer was supplied by the 3139 application 3141 Note that in the absence of message boundary preservation or a 3142 Message Framer, all bytes received on the Connection will be 3143 represented as one large Message of indeterminate length. 3145 In the following example, an application only wants to receive up to 3146 1000 bytes at a time from a Connection. If a 1500-byte message 3147 arrives, it would receive the message in two separate ReceivedPartial 3148 events. 3150 Connection.Receive(1, 1000) 3152 // Receive first 1000 bytes, message is incomplete 3153 Connection -> ReceivedPartial 3155 Connection.Receive(1, 1000) 3157 // Receive last 500 bytes, message is now complete 3158 Connection -> ReceivedPartial 3160 9.3.2.3. ReceiveError 3162 Connection -> ReceiveError 3164 A ReceiveError occurs when data is received by the underlying 3165 Protocol Stack that cannot be fully retrieved or parsed, and when it 3166 is useful for the application to be notified of such errors. For 3167 example, a ReceiveError can indicate that a Message (identified via 3168 the MessageContext) that was being partially received previously, but 3169 had not completed, encountered an error and will not be completed. 3170 This can be useful for an application, which may want to use this 3171 error as a hint to remove previously received Message parts from 3172 memory. As another example, if an incoming Message does not fulfill 3173 the Required Minimum Corruption Protection Coverage for Receiving 3174 property (see Section 8.1.1), an application can use this error as a 3175 hint to inform the peer application to adjust the Sending Corruption 3176 Protection Length property (see Section 9.1.3.6). 3178 In contrast, internal protocol reception errors (e.g., loss causing 3179 retransmissions in TCP) are not signalled by this Event. Conditions 3180 that irrevocably lead to the termination of the Connection are 3181 signaled using ConnectionError (see Section 10). 3183 9.3.3. Receive Message Properties 3185 Each Message Context may contain metadata from protocols in the 3186 Protocol Stack; which metadata is available is Protocol Stack 3187 dependent. These are exposed through additional read-only Message 3188 Properties that can be queried from the MessageContext object (see 3189 Section 9.1.1) passed by the receive event. The following metadata 3190 values are supported: 3192 9.3.3.1. UDP(-Lite)-specific Property: ECN 3194 When available, Message metadata carries the value of the Explicit 3195 Congestion Notification (ECN) field. This information can be used 3196 for logging and debugging, and for building applications that need 3197 access to information about the transport internals for their own 3198 operation. This property is specific to UDP and UDP-Lite because 3199 these protocols do not implement congestion control, and hence expose 3200 this functionality to the application (see [RFC8293], following the 3201 guidance in [RFC8085]) 3203 9.3.3.2. Early Data 3205 In some cases it can be valuable to know whether data was read as 3206 part of early data transfer (before connection establishment has 3207 finished). This is useful if applications need to treat early data 3208 separately, e.g., if early data has different security properties 3209 than data sent after connection establishment. In the case of TLS 3210 1.3, client early data can be replayed maliciously (see [RFC8446]). 3211 Thus, receivers might wish to perform additional checks for early 3212 data to ensure it is safely replayable. If TLS 1.3 is available and 3213 the recipient Message was sent as part of early data, the 3214 corresponding metadata carries a flag indicating as such. If early 3215 data is enabled, applications should check this metadata field for 3216 Messages received during connection establishment and respond 3217 accordingly. 3219 9.3.3.3. Receiving Final Messages 3221 The Message Context can indicate whether or not this Message is the 3222 Final Message on a Connection. For any Message that is marked as 3223 Final, the application can assume that there will be no more Messages 3224 received on the Connection once the Message has been completely 3225 delivered. This corresponds to the Final property that may be marked 3226 on a sent Message, see Section 9.1.3.5. 3228 Some transport protocols and peers do not support signaling of the 3229 Final property. Applications therefore should not rely on receiving 3230 a Message marked Final to know that the sending endpoint is done 3231 sending on a connection. 3233 Any calls to Receive once the Final Message has been delivered will 3234 result in errors. 3236 10. Connection Termination 3238 A Connection can be terminated i) by the Local Endpoint (i.e., the 3239 application calls the Close, CloseGroup, Abort or AbortGroup Action), 3240 ii) by the Remote Endpoint (i.e., the remote application calls the 3241 Close, CloseGroup, Abort or AbortGroup Action), or iii) because of an 3242 error (e.g., a timeout). A local call of the Close Action will cause 3243 the Connection to either send a Closed Event or a ConnectionError 3244 Event, and a local call of the CloseGroup Action will cause all of 3245 the Connections in the group to either send a Closed Event or a 3246 ConnectionError Event. A local call of the Abort Action will cause 3247 the Connection to send a ConnectionError Event, indicating local 3248 Abort as a reason, and a local call of the AbortGroup Action will 3249 cause all of the Connections in the group to send a ConnectionError 3250 Event, indicating local Abort as a reason. 3252 Remote Action calls map to Events similar to local calls (e.g., a 3253 remote Close causes the Connection to either send a Closed Event or a 3254 ConnectionError Event), but, different from local Action calls, it is 3255 not guaranteed that such Events will indeed be invoked. When an 3256 application needs to free resources associated with a Connection, it 3257 should therefore not rely on the invocation of such Events due to 3258 termination calls from the Remote Endpoint, but instead use the local 3259 termination Actions. 3261 Close terminates a Connection after satisfying all the requirements 3262 that were specified regarding the delivery of Messages that the 3263 application has already given to the Transport Services system. Upon 3264 successfully satisfying all these requirements, the Connection will 3265 send the Closed Event. For example, if reliable delivery was 3266 requested for a Message handed over before calling Close, the Closed 3267 Event will signify that this Message has indeed been delivered. This 3268 Action does not affect any other Connection in the same Connection 3269 Group. 3271 Connection.Close() 3272 The Closed Event informs the application that a Close Action has 3273 successfully completed, or that the Remote Endpoint has closed the 3274 Connection. There is no guarantee that a remote Close will be 3275 signaled. 3277 Connection -> Closed<> 3279 Abort terminates a Connection without delivering any remaining 3280 Messages. This action does not affect any other Connection that is 3281 entangled with this one in a Connection Group. When the Abort Action 3282 has finished, the Connection will send a ConnectionError Event, 3283 indicating local Abort as a reason. 3285 Connection.Abort() 3287 CloseGroup gracefully terminates a Connection and any other 3288 Connections in the same Connection Group. For example, all of the 3289 Connections in a group might be streams of a single session for a 3290 multistreaming protocol; closing the entire group will close the 3291 underlying session. See also Section 7.4. All Connections in the 3292 group will send a Closed Event when the CloseGroup Action was 3293 successful. As with Close, any Messages remaining to be processed on 3294 a Connection will be handled prior to closing. 3296 Connection.CloseGroup() 3298 AbortGroup terminates a Connection and any other Connections that are 3299 in the same Connection Group without delivering any remaining 3300 Messages. When the AbortGroup Action has finished, all Connections 3301 in the group will send a ConnectionError Event, indicating local 3302 Abort as a reason. 3304 Connection.AbortGroup() 3306 A ConnectionError informs the application that: 1) data could not be 3307 delivered to the peer after a timeout, or 2) the Connection has been 3308 aborted (e.g., because the peer has called Abort). There is no 3309 guarantee that an Abort from the peer will be signaled. 3311 Connection -> ConnectionError 3313 11. Connection State and Ordering of Operations and Events 3315 This Transport Services API is designed to be independent of an 3316 implementation's concurrency model. The details of how exactly 3317 actions are handled, and how events are dispatched, are 3318 implementation dependent. 3320 Each transition of connection state is associated with one of more 3321 events: 3323 * Ready<> occurs when a Connection created with Initiate() or 3324 InitiateWithSend() transitions to Established state. 3326 * ConnectionReceived<> occurs when a Connection created with 3327 Listen() transitions to Established state. 3329 * RendezvousDone<> occurs when a Connection created with 3330 Rendezvous() transitions to Established state. 3332 * Closed<> occurs when a Connection transitions to Closed state 3333 without error. 3335 * EstablishmentError<> occurs when a Connection created with 3336 Initiate() transitions from Establishing state to Closed state due 3337 to an error. 3339 * ConnectionError<> occurs when a Connection transitions to Closed 3340 state due to an error in all other circumstances. 3342 The following diagram shows the possible states of a Connection and 3343 the events that occur upon a transition from one state to another. 3345 (*) (**) 3346 Establishing -----> Established -----> Closing ------> Closed 3347 | ^ 3348 | | 3349 +---------------------------------------------------+ 3350 EstablishmentError<> 3352 (*) Ready<>, ConnectionReceived<>, RendezvousDone<> 3353 (**) Closed<>, ConnectionError<> 3355 Figure 2: Connection State Diagram 3357 The Transport Services API provides the following guarantees about 3358 the ordering of operations: 3360 * Sent<> events will occur on a Connection in the order in which the 3361 Messages were sent (i.e., delivered to the kernel or to the 3362 network interface, depending on implementation). 3364 * Received<> will never occur on a Connection before it is 3365 Established; i.e. before a Ready<> event on that Connection, or a 3366 ConnectionReceived<> or RendezvousDone<> containing that 3367 Connection. 3369 * No events will occur on a Connection after it is Closed; i.e., 3370 after a Closed<> event, an EstablishmentError<> or 3371 ConnectionError<> will not occur on that connection. To ensure 3372 this ordering, Closed<> will not occur on a Connection while other 3373 events on the Connection are still locally outstanding (i.e., 3374 known to the Transport Services API and waiting to be dealt with 3375 by the application). 3377 12. IANA Considerations 3379 RFC-EDITOR: Please remove this section before publication. 3381 This document has no Actions for IANA. Later versions of this 3382 document may create IANA registries for generic transport property 3383 names and transport property namespaces (see Section 4.1). 3385 13. Privacy and Security Considerations 3387 This document describes a generic API for interacting with a 3388 Transport Services system. Part of this API includes configuration 3389 details for transport security protocols, as discussed in 3390 Section 6.3. It does not recommend use (or disuse) of specific 3391 algorithms or protocols. Any API-compatible transport security 3392 protocol ought to work in a Transport Services system. Security 3393 considerations for these protocols are discussed in the respective 3394 specifications. 3396 The described API is used to exchange information between an 3397 application and the Transport Services system. While it is not 3398 necessarily expected that both systems are implemented by the same 3399 authority, it is expected that the Transport Services system 3400 implementation is either provided as a library that is selected by 3401 the application from a trusted party, or that it is part of the 3402 operating system that the application also relies on for other tasks. 3404 In either case, the Transport Services API is an internal interface 3405 that is used to change information locally between two systems. 3406 However, as the Transport Services system is responsible for network 3407 communication, it is in the position to potentially share any 3408 information provided by the application with the network or another 3409 communication peer. Most of the information provided over the 3410 Transport Services API are useful to configure and select protocols 3411 and paths and are not necessarily privacy sensitive. Still, some 3412 information could be privacy sensitive because it might reveal usage 3413 characteristics and habits of the user of an application. 3415 Of course any communication over a network reveals usage 3416 characteristics, as all packets, as well as their timing and size, 3417 are part of the network-visible wire image [RFC8546]. However, the 3418 selection of a protocol and its configuration also impacts which 3419 information is visible, potentially in clear text, and which other 3420 entities can access it. In most cases, information provided for 3421 protocol and path selection should not directly translate to 3422 information that can be observed by network devices on the path. 3423 However, there might be specific configuration information that is 3424 intended for path exposure, e.g., a DiffServ codepoint setting, that 3425 is either provided directly by the application or indirectly 3426 configured for a traffic profile. 3428 Applications should be aware that communication attempts can lead to 3429 more than one connection establishment. This is the case, for 3430 example, when the Transport Services system also executes name 3431 resolution, when support mechanisms such as TURN or ICE are used to 3432 establish connectivity, if protocols or paths are raised, or if a 3433 path fails and fallback or re-establishment is supported in the 3434 Transport Services system. 3436 Applications should also take care to not assume that all data 3437 received using the Transport Services API is always complete or well- 3438 formed. Specifically, messages that are received partially 3439 Section 9.3.2.2 could be a source of truncation attacks if 3440 applications do not distinguish between partial messages and complete 3441 messages. 3443 The Transport Services API explicitly does not require the 3444 application to resolve names, though there is a tradeoff between 3445 early and late binding of addresses to names. Early binding allows 3446 the API implementation to reduce connection setup latency, at the 3447 cost of potentially limited scope for alternate path discovery during 3448 Connection establishment, as well as potential additional information 3449 leakage about application interest when used with a resolution method 3450 (such as DNS without TLS) which does not protect query 3451 confidentiality. 3453 These communication activities are not different from what is used 3454 today. However, the goal of a Transport Services system is to 3455 support such mechanisms as a generic service within the transport 3456 layer. This enables applications to more dynamically benefit from 3457 innovations and new protocols in the transport, although it reduces 3458 transparency of the underlying communication actions to the 3459 application itself. The Transport Services API is designed such that 3460 protocol and path selection can be limited to a small and controlled 3461 set if required by the application for functional or security 3462 purposes. Further, A Transport Services system should provide an 3463 interface to poll information about which protocol and path is 3464 currently in use as well as provide logging about the communication 3465 events of each connection. 3467 14. Acknowledgements 3469 This work has received funding from the European Union's Horizon 2020 3470 research and innovation programme under grant agreements No. 644334 3471 (NEAT) and No. 688421 (MAMI). 3473 This work has been supported by Leibniz Prize project funds of DFG - 3474 German Research Foundation: Gottfried Wilhelm Leibniz-Preis 2011 (FKZ 3475 FE 570/4-1). 3477 This work has been supported by the UK Engineering and Physical 3478 Sciences Research Council under grant EP/R04144X/1. 3480 This work has been supported by the Research Council of Norway under 3481 its "Toppforsk" programme through the "OCARINA" project. 3483 Thanks to Stuart Cheshire, Josh Graessley, David Schinazi, and Eric 3484 Kinnear for their implementation and design efforts, including Happy 3485 Eyeballs, that heavily influenced this work. Thanks to Laurent Chuat 3486 and Jason Lee for initial work on the Post Sockets interface, from 3487 which this work has evolved. Thanks to Maximilian Franke for asking 3488 good questions based on implementation experience and for 3489 contributing text, e.g., on multicast. 3491 15. References 3493 15.1. Normative References 3495 [I-D.ietf-taps-arch] 3496 Pauly, T., Trammell, B., Brunstrom, A., Fairhurst, G., 3497 Perkins, C., Tiesel, P. S., and C. A. Wood, "An 3498 Architecture for Transport Services", Work in Progress, 3499 Internet-Draft, draft-ietf-taps-arch-11, 12 July 2021, 3500 . 3503 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3504 Requirement Levels", BCP 14, RFC 2119, 3505 DOI 10.17487/RFC2119, March 1997, 3506 . 3508 [RFC2914] Floyd, S., "Congestion Control Principles", BCP 41, 3509 RFC 2914, DOI 10.17487/RFC2914, September 2000, 3510 . 3512 [RFC4941] Narten, T., Draves, R., and S. Krishnan, "Privacy 3513 Extensions for Stateless Address Autoconfiguration in 3514 IPv6", RFC 4941, DOI 10.17487/RFC4941, September 2007, 3515 . 3517 [RFC8084] Fairhurst, G., "Network Transport Circuit Breakers", 3518 BCP 208, RFC 8084, DOI 10.17487/RFC8084, March 2017, 3519 . 3521 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 3522 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 3523 March 2017, . 3525 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3526 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3527 May 2017, . 3529 [RFC8303] Welzl, M., Tuexen, M., and N. Khademi, "On the Usage of 3530 Transport Features Provided by IETF Transport Protocols", 3531 RFC 8303, DOI 10.17487/RFC8303, February 2018, 3532 . 3534 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3535 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3536 . 3538 15.2. Informative References 3540 [I-D.ietf-httpbis-priority] 3541 Oku, K. and L. Pardue, "Extensible Prioritization Scheme 3542 for HTTP", Work in Progress, Internet-Draft, draft-ietf- 3543 httpbis-priority-11, 8 December 2021, 3544 . 3547 [I-D.ietf-taps-impl] 3548 Brunstrom, A., Pauly, T., Enghardt, T., Grinnemo, K., 3549 Jones, T., Tiesel, P. S., Perkins, C., and M. Welzl, 3550 "Implementing Interfaces to Transport Services", Work in 3551 Progress, Internet-Draft, draft-ietf-taps-impl-10, 12 July 3552 2021, . 3555 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 3556 "Definition of the Differentiated Services Field (DS 3557 Field) in the IPv4 and IPv6 Headers", RFC 2474, 3558 DOI 10.17487/RFC2474, December 1998, 3559 . 3561 [RFC2597] Heinanen, J., Baker, F., Weiss, W., and J. Wroclawski, 3562 "Assured Forwarding PHB Group", RFC 2597, 3563 DOI 10.17487/RFC2597, June 1999, 3564 . 3566 [RFC3246] Davie, B., Charny, A., Bennet, J.C.R., Benson, K., Le 3567 Boudec, J.Y., Courtney, W., Davari, S., Firoiu, V., and D. 3568 Stiliadis, "An Expedited Forwarding PHB (Per-Hop 3569 Behavior)", RFC 3246, DOI 10.17487/RFC3246, March 2002, 3570 . 3572 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 3573 A., Peterson, J., Sparks, R., Handley, M., and E. 3574 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 3575 DOI 10.17487/RFC3261, June 2002, 3576 . 3578 [RFC3376] Cain, B., Deering, S., Kouvelas, I., Fenner, B., and A. 3579 Thyagarajan, "Internet Group Management Protocol, Version 3580 3", RFC 3376, DOI 10.17487/RFC3376, October 2002, 3581 . 3583 [RFC4594] Babiarz, J., Chan, K., and F. Baker, "Configuration 3584 Guidelines for DiffServ Service Classes", RFC 4594, 3585 DOI 10.17487/RFC4594, August 2006, 3586 . 3588 [RFC4604] Holbrook, H., Cain, B., and B. Haberman, "Using Internet 3589 Group Management Protocol Version 3 (IGMPv3) and Multicast 3590 Listener Discovery Protocol Version 2 (MLDv2) for Source- 3591 Specific Multicast", RFC 4604, DOI 10.17487/RFC4604, 3592 August 2006, . 3594 [RFC5245] Rosenberg, J., "Interactive Connectivity Establishment 3595 (ICE): A Protocol for Network Address Translator (NAT) 3596 Traversal for Offer/Answer Protocols", RFC 5245, 3597 DOI 10.17487/RFC5245, April 2010, 3598 . 3600 [RFC5482] Eggert, L. and F. Gont, "TCP User Timeout Option", 3601 RFC 5482, DOI 10.17487/RFC5482, March 2009, 3602 . 3604 [RFC5766] Mahy, R., Matthews, P., and J. Rosenberg, "Traversal Using 3605 Relays around NAT (TURN): Relay Extensions to Session 3606 Traversal Utilities for NAT (STUN)", RFC 5766, 3607 DOI 10.17487/RFC5766, April 2010, 3608 . 3610 [RFC5865] Baker, F., Polk, J., and M. Dolly, "A Differentiated 3611 Services Code Point (DSCP) for Capacity-Admitted Traffic", 3612 RFC 5865, DOI 10.17487/RFC5865, May 2010, 3613 . 3615 [RFC7478] Holmberg, C., Hakansson, S., and G. Eriksson, "Web Real- 3616 Time Communication Use Cases and Requirements", RFC 7478, 3617 DOI 10.17487/RFC7478, March 2015, 3618 . 3620 [RFC7556] Anipko, D., Ed., "Multiple Provisioning Domain 3621 Architecture", RFC 7556, DOI 10.17487/RFC7556, June 2015, 3622 . 3624 [RFC7657] Black, D., Ed. and P. Jones, "Differentiated Services 3625 (Diffserv) and Real-Time Communication", RFC 7657, 3626 DOI 10.17487/RFC7657, November 2015, 3627 . 3629 [RFC8095] Fairhurst, G., Ed., Trammell, B., Ed., and M. Kuehlewind, 3630 Ed., "Services Provided by IETF Transport Protocols and 3631 Congestion Control Mechanisms", RFC 8095, 3632 DOI 10.17487/RFC8095, March 2017, 3633 . 3635 [RFC8229] Pauly, T., Touati, S., and R. Mantha, "TCP Encapsulation 3636 of IKE and IPsec Packets", RFC 8229, DOI 10.17487/RFC8229, 3637 August 2017, . 3639 [RFC8260] Stewart, R., Tuexen, M., Loreto, S., and R. Seggelmann, 3640 "Stream Schedulers and User Message Interleaving for the 3641 Stream Control Transmission Protocol", RFC 8260, 3642 DOI 10.17487/RFC8260, November 2017, 3643 . 3645 [RFC8293] Ghanwani, A., Dunbar, L., McBride, M., Bannai, V., and R. 3646 Krishnan, "A Framework for Multicast in Network 3647 Virtualization over Layer 3", RFC 8293, 3648 DOI 10.17487/RFC8293, January 2018, 3649 . 3651 [RFC8489] Petit-Huguenin, M., Salgueiro, G., Rosenberg, J., Wing, 3652 D., Mahy, R., and P. Matthews, "Session Traversal 3653 Utilities for NAT (STUN)", RFC 8489, DOI 10.17487/RFC8489, 3654 February 2020, . 3656 [RFC8546] Trammell, B. and M. Kuehlewind, "The Wire Image of a 3657 Network Protocol", RFC 8546, DOI 10.17487/RFC8546, April 3658 2019, . 3660 [RFC8622] Bless, R., "A Lower-Effort Per-Hop Behavior (LE PHB) for 3661 Differentiated Services", RFC 8622, DOI 10.17487/RFC8622, 3662 June 2019, . 3664 [RFC8699] Islam, S., Welzl, M., and S. Gjessing, "Coupled Congestion 3665 Control for RTP Media", RFC 8699, DOI 10.17487/RFC8699, 3666 January 2020, . 3668 [RFC8838] Ivov, E., Uberti, J., and P. Saint-Andre, "Trickle ICE: 3669 Incremental Provisioning of Candidates for the Interactive 3670 Connectivity Establishment (ICE) Protocol", RFC 8838, 3671 DOI 10.17487/RFC8838, January 2021, 3672 . 3674 [RFC8899] Fairhurst, G., Jones, T., Tüxen, M., Rüngeler, I., and T. 3675 Völker, "Packetization Layer Path MTU Discovery for 3676 Datagram Transports", RFC 8899, DOI 10.17487/RFC8899, 3677 September 2020, . 3679 [RFC8922] Enghardt, T., Pauly, T., Perkins, C., Rose, K., and C. 3680 Wood, "A Survey of the Interaction between Security 3681 Protocols and Transport Services", RFC 8922, 3682 DOI 10.17487/RFC8922, October 2020, 3683 . 3685 [RFC8923] Welzl, M. and S. Gjessing, "A Minimal Set of Transport 3686 Services for End Systems", RFC 8923, DOI 10.17487/RFC8923, 3687 October 2020, . 3689 [TCP-COUPLING] 3690 Islam, S., Welzl, M., Hiorth, K., Hayes, D., Armitage, G., 3691 and S. Gjessing, "ctrlTCP: Reducing Latency through 3692 Coupled, Heterogeneous Multi-Flow TCP Congestion Control", 3693 IEEE INFOCOM Global Internet Symposium (GI) workshop (GI 3694 2018) , 2018. 3696 Appendix A. Implementation Mapping 3698 The way the concepts from this abstract API map into concrete APIs in 3699 a given language on a given platform largely depends on the features 3700 and norms of the language and the platform. Actions could be 3701 implemented as functions or method calls, for instance, and Events 3702 could be implemented via event queues, handler functions or classes, 3703 communicating sequential processes, or other asynchronous calling 3704 conventions. 3706 A.1. Types 3708 The basic types mentioned in Section 1.1 typically have natural 3709 correspondences in practical programming languages, perhaps 3710 constrained by implementation-specific limitations. For example: 3712 * An Integer can typically be represented in C by an int or long, 3713 subject to the underlying platform's ranges for each. 3715 * In C, a Tuple may be represented as a struct with one member for 3716 each of the value types in the ordered grouping. In Python, by 3717 contrast, a Tuple may be represented natively as a tuple, a 3718 sequence of dynamically-typed elements. 3720 * A Collection may be represented as a std::set in C++ or as a set 3721 in Python. In C, it may be represented as an array or as a 3722 higher-level data structure with appropriate accessors defined. 3724 The objects described in Section 1.1 can similarly be represented in 3725 different ways depending on which programming language is used. 3726 Objects like Preconnections, Connections, and Listeners can be long- 3727 lived, and benefit from using object-oriented constructs. Note that 3728 in C, these objects may need to provide a way to release or free 3729 their underlying memory when the application is done using them. For 3730 example, since a Preconnection can be used to initiate multiple 3731 Connections, it is the responsibility of the application to clean up 3732 the Preconnection memory if necessary. 3734 A.2. Events and Errors 3736 This specification treats Events and Errors similarly. Errors, just 3737 as any other Events, may occur asynchronously in network 3738 applications. However, implementations of this API may report Errors 3739 synchronously, according to the error handling idioms of the 3740 implementation platform, where they can be immediately detected, such 3741 as by generating an exception when attempting to initiate a 3742 connection with inconsistent Transport Properties. An error can 3743 provide an optional reason to the application with further details 3744 about why the error occurred. 3746 A.3. Time Duration 3748 Time duration types are implementation-specific. For instance, it 3749 could be a number of seconds, number of milliseconds, or a struct 3750 timeval in C or a user-defined Duration class in C++. 3752 Appendix B. Convenience Functions 3754 B.1. Adding Preference Properties 3756 As Selection Properties of type Preference will be set on a 3757 TransportProperties object quite frequently, implementations can 3758 provide special actions for adding each preference level i.e, 3759 TransportProperties.Set(some_property, avoid) is equivalent to 3760 TransportProperties.Avoid(some_property): 3762 TransportProperties.Require(property) 3763 TransportProperties.Prefer(property) 3764 TransportProperties.Ignore(property) 3765 TransportProperties.Avoid(property) 3766 TransportProperties.Prohibit(property) 3768 B.2. Transport Property Profiles 3770 To ease the use of the Transport Services API specified by this 3771 document, implementations can provide a mechanism to create Transport 3772 Property objects (see Section 6.2) that are pre-configured with 3773 frequently used sets of properties; the following are in common use 3774 in current applications: 3776 B.2.1. reliable-inorder-stream 3778 This profile provides reliable, in-order transport service with 3779 congestion control. TCP is an example of a protocol that provides 3780 this service. It should consist of the following properties: 3782 +=======================+=========+ 3783 | Property | Value | 3784 +=======================+=========+ 3785 | reliability | require | 3786 +-----------------------+---------+ 3787 | preserveOrder | require | 3788 +-----------------------+---------+ 3789 | congestionControl | require | 3790 +-----------------------+---------+ 3791 | preserveMsgBoundaries | ignore | 3792 +-----------------------+---------+ 3794 Table 2: reliable-inorder- 3795 stream preferences 3797 B.2.2. reliable-message 3799 This profile provides message-preserving, reliable, in-order 3800 transport service with congestion control. SCTP is an example of a 3801 protocol that provides this service. It should consist of the 3802 following properties: 3804 +=======================+=========+ 3805 | Property | Value | 3806 +=======================+=========+ 3807 | reliability | require | 3808 +-----------------------+---------+ 3809 | preserveOrder | require | 3810 +-----------------------+---------+ 3811 | congestionControl | require | 3812 +-----------------------+---------+ 3813 | preserveMsgBoundaries | require | 3814 +-----------------------+---------+ 3816 Table 3: reliable-message 3817 preferences 3819 B.2.3. unreliable-datagram 3821 This profile provides a datagram transport service without any 3822 reliability guarantee. An example of a protocol that provides this 3823 service is UDP. It consists of the following properties: 3825 +=======================+=========+ 3826 | Property | Value | 3827 +=======================+=========+ 3828 | reliability | avoid | 3829 +-----------------------+---------+ 3830 | preserveOrder | avoid | 3831 +-----------------------+---------+ 3832 | congestionControl | ignore | 3833 +-----------------------+---------+ 3834 | preserveMsgBoundaries | require | 3835 +-----------------------+---------+ 3836 | safely replayable | true | 3837 +-----------------------+---------+ 3839 Table 4: unreliable-datagram 3840 preferences 3842 Applications that choose this Transport Property Profile would avoid 3843 the additional latency that could be introduced by retransmission or 3844 reordering in a transport protocol. 3846 Applications that choose this Transport Property Profile to reduce 3847 latency should also consider setting an appropriate Capacity Profile 3848 Property, see Section 8.1.6 and might benefit from controlling 3849 checksum coverage, see Section 6.2.7 and Section 6.2.8. 3851 Appendix C. Relationship to the Minimal Set of Transport Services for 3852 End Systems 3854 [RFC8923] identifies a minimal set of transport services that end 3855 systems should offer. These services make all non-security-related 3856 transport features of TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT 3857 available that 1) require interaction with the application, and 2) do 3858 not get in the way of a possible implementation over TCP (or, with 3859 limitations, UDP). The following text explains how this minimal set 3860 is reflected in the present API. For brevity, it is based on the 3861 list in Section 4.1 of [RFC8923], updated according to the discussion 3862 in Section 5 of [RFC8923]. The present API covers all elements of 3863 this section. This list is a subset of the transport features in 3864 Appendix A of [RFC8923], which refers to the primitives in "pass 2" 3865 (Section 4) of [RFC8303] for further details on the implementation 3866 with TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT. 3868 * Connect: Initiate Action (Section 7.1). 3870 * Listen: Listen Action (Section 7.2). 3872 * Specify number of attempts and/or timeout for the first 3873 establishment message: timeout parameter of Initiate (Section 7.1) 3874 or InitiateWithSend Action (Section 9.2.5). 3876 * Disable MPTCP: multipath Property (Section 6.2.14). 3878 * Hand over a message to reliably transfer (possibly multiple times) 3879 before connection establishment: InitiateWithSend Action 3880 (Section 9.2.5). 3882 * Change timeout for aborting connection (using retransmit limit or 3883 time value): connTimeout property, using a time value 3884 (Section 8.1.3). 3886 * Timeout event when data could not be delivered for too long: 3887 ConnectionError Event (Section 10). 3889 * Suggest timeout to the peer: See "TCP-specific Properties: User 3890 Timeout Option (UTO)" (Section 8.2). 3892 * Notification of ICMP error message arrival: softErrorNotify 3893 (Section 6.2.17) and SoftError Event (Section 8.3.1). 3895 * Choose a scheduler to operate between streams of an association: 3896 connScheduler property (Section 8.1.5). 3898 * Configure priority or weight for a scheduler: connPriority 3899 property (Section 8.1.2). 3901 * "Specify checksum coverage used by the sender" and "Disable 3902 checksum when sending": msgChecksumLen property (Section 9.1.3.6) 3903 and fullChecksumSend property (Section 6.2.7). 3905 * "Specify minimum checksum coverage required by receiver" and 3906 "Disable checksum requirement when receiving": recvChecksumLen 3907 property (Section 8.1.1) and fullChecksumRecv property 3908 (Section 6.2.8). 3910 * "Specify DF field": noFragmentation property (Section 9.1.3.9). 3912 * Get max. transport-message size that may be sent using a non- 3913 fragmented IP packet from the configured interface: 3914 singularTransmissionMsgMaxLen property (Section 8.1.11.2). 3916 * Get max. transport-message size that may be received from the 3917 configured interface: recvMsgMaxLen property (Section 8.1.11.4). 3919 * Obtain ECN field: This is a read-only Message Property of the 3920 MessageContext object (see "UDP(-Lite)-specific Property: ECN" 3921 Section 9.3.3.1). 3923 * "Specify DSCP field", "Disable Nagle algorithm", "Enable and 3924 configure a Low Extra Delay Background Transfer": as suggested in 3925 Section 5.5 of [RFC8923], these transport features are 3926 collectively offered via the connCapacityProfile property 3927 (Section 8.1.6). Per-Message control ("Request not to bundle 3928 messages") is offered via the msgCapacityProfile property 3929 (Section 9.1.3.8). 3931 * Close after reliably delivering all remaining data, causing an 3932 event informing the application on the other side: this is offered 3933 by the Close Action with slightly changed semantics in line with 3934 the discussion in Section 5.2 of [RFC8923] (Section 10). 3936 * "Abort without delivering remaining data, causing an event 3937 informing the application on the other side" and "Abort without 3938 delivering remaining data, not causing an event informing the 3939 application on the other side": this is offered by the Abort 3940 action without promising that this is signaled to the other side. 3941 If it is, a ConnectionError Event will be invoked at the peer 3942 (Section 10). 3944 * "Reliably transfer data, with congestion control", "Reliably 3945 transfer a message, with congestion control" and "Unreliably 3946 transfer a message": data is transferred via the Send action 3947 (Section 9.2). Reliability is controlled via the reliability 3948 (Section 6.2.1) property and the msgReliable Message Property 3949 (Section 9.1.3.7). Transmitting data as a message or without 3950 delimiters is controlled via Message Framers (Section 9.1.2). The 3951 choice of congestion control is provided via the congestionControl 3952 property (Section 6.2.9). 3954 * Configurable Message Reliability: the msgLifetime Message Property 3955 implements a time-based way to configure message reliability 3956 (Section 9.1.3.1). 3958 * "Ordered message delivery (potentially slower than unordered)" and 3959 "Unordered message delivery (potentially faster than ordered)": 3960 these two transport features are controlled via the Message 3961 Property msgOrdered (Section 9.1.3.3). 3963 * Request not to delay the acknowledgement (SACK) of a message: 3964 should the protocol support it, this is one of the transport 3965 features the Transport Services system can apply when an 3966 application uses the connCapacityProfile Property (Section 8.1.6) 3967 or the msgCapacityProfile Message Property (Section 9.1.3.8) with 3968 value Low Latency/Interactive. 3970 * Receive data (with no message delimiting): Receive Action 3971 (Section 9.3) and Received Event (Section 9.3.2.1). 3973 * Receive a message: Receive Action (Section 9.3) and Received Event 3974 (Section 9.3.2.1), using Message Framers (Section 9.1.2). 3976 * Information about partial message arrival: Receive Action 3977 (Section 9.3) and ReceivedPartial Event (Section 9.3.2.2). 3979 * Notification of send failures: Expired Event (Section 9.2.2.2) and 3980 SendError Event (Section 9.2.2.3). 3982 * Notification that the stack has no more user data to send: 3983 applications can obtain this information via the Sent Event 3984 (Section 9.2.2.1). 3986 * Notification to a receiver that a partial message delivery has 3987 been aborted: ReceiveError Event (Section 9.3.2.3). 3989 * Notification of Excessive Retransmissions (early warning below 3990 abortion threshold): SoftError Event (Section 8.3.1). 3992 Authors' Addresses 3994 Brian Trammell (editor) 3995 Google Switzerland GmbH 3996 Gustav-Gull-Platz 1 3997 CH- 8004 Zurich 3998 Switzerland 4000 Email: ietf@trammell.ch 4002 Michael Welzl (editor) 4003 University of Oslo 4004 PO Box 1080 Blindern 4005 0316 Oslo 4006 Norway 4008 Email: michawe@ifi.uio.no 4010 Theresa Enghardt 4011 Netflix 4012 121 Albright Way 4013 Los Gatos, CA 95032, 4014 United States of America 4016 Email: ietf@tenghardt.net 4018 Godred Fairhurst 4019 University of Aberdeen 4020 Fraser Noble Building 4021 Aberdeen, AB24 3UE 4023 Email: gorry@erg.abdn.ac.uk 4024 URI: http://www.erg.abdn.ac.uk/ 4026 Mirja Kuehlewind 4027 Ericsson 4028 Ericsson-Allee 1 4029 Herzogenrath 4030 Germany 4032 Email: mirja.kuehlewind@ericsson.com 4033 Colin Perkins 4034 University of Glasgow 4035 School of Computing Science 4036 Glasgow G12 8QQ 4037 United Kingdom 4039 Email: csp@csperkins.org 4041 Philipp S. Tiesel 4042 SAP SE 4043 Konrad-Zuse-Ring 10 4044 14469 Potsdam 4045 Germany 4047 Email: philipp@tiesel.net 4049 Christopher A. Wood 4050 Cloudflare 4051 101 Townsend St 4052 San Francisco, 4053 United States of America 4055 Email: caw@heapingbits.net 4057 Tommy Pauly 4058 Apple Inc. 4059 One Apple Park Way 4060 Cupertino, California 95014, 4061 United States of America 4063 Email: tpauly@apple.com 4065 Kyle Rose 4066 Akamai Technologies, Inc. 4067 145 Broadway 4068 Cambridge, MA, 4069 United States of America 4071 Email: krose@krose.org