idnits 2.17.1 draft-ietf-taps-interface-13.txt: -(3479): 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 (12 July 2021) is 1017 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 525, but not defined == Missing Reference: 'StunCandidate' is mentioned on line 525, but not defined == Outdated reference: A later version (-19) exists of draft-ietf-taps-arch-10 ** 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-03 == Outdated reference: A later version (-18) exists of draft-ietf-taps-impl-09 -- 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: 13 January 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 12 July 2021 24 An Abstract Application Layer Interface to Transport Services 25 draft-ietf-taps-interface-13 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 traditional BSD sockets API as the common interface to 37 the transport layer, in an environment where endpoints could select 38 from multiple 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 13 January 2022. 57 Copyright Notice 59 Copyright (c) 2021 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 Simplified BSD License text 68 as described in Section 4.e of the Trust Legal Provisions and are 69 provided without warranty as described in the Simplified 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 Interface Design . . . . . . . . . . . . . . . . 7 77 3. API Summary . . . . . . . . . . . . . . . . . . . . . . . . . 8 78 3.1. Usage Examples . . . . . . . . . . . . . . . . . . . . . 9 79 3.1.1. Server Example . . . . . . . . . . . . . . . . . . . 10 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 . . . . . . . . . . . . . . . . 13 84 4.2. Transport Property Types . . . . . . . . . . . . . . . . 14 85 5. Scope of the Interface Definition . . . . . . . . . . . . . . 15 86 6. Pre-Establishment Phase . . . . . . . . . . . . . . . . . . . 16 87 6.1. Specifying Endpoints . . . . . . . . . . . . . . . . . . 17 88 6.1.1. Using Multicast Endpoints . . . . . . . . . . . . . . 18 89 6.1.2. Endpoint Aliases . . . . . . . . . . . . . . . . . . 18 90 6.1.3. Endpoint Examples . . . . . . . . . . . . . . . . . . 19 91 6.2. Specifying Transport Properties . . . . . . . . . . . . . 20 92 6.2.1. Reliable Data Transfer (Connection) . . . . . . . . . 23 93 6.2.2. Preservation of Message Boundaries . . . . . . . . . 23 94 6.2.3. Configure Per-Message Reliability . . . . . . . . . . 24 95 6.2.4. Preservation of Data Ordering . . . . . . . . . . . . 24 96 6.2.5. Use 0-RTT Session Establishment with a Safely 97 Replayable Message . . . . . . . . . . . . . . . . . 24 99 6.2.6. Multistream Connections in Group . . . . . . . . . . 24 100 6.2.7. Full Checksum Coverage on Sending . . . . . . . . . . 25 101 6.2.8. Full Checksum Coverage on Receiving . . . . . . . . . 25 102 6.2.9. Congestion control . . . . . . . . . . . . . . . . . 25 103 6.2.10. Keep alive . . . . . . . . . . . . . . . . . . . . . 26 104 6.2.11. Interface Instance or Type . . . . . . . . . . . . . 26 105 6.2.12. Provisioning Domain Instance or Type . . . . . . . . 27 106 6.2.13. Use Temporary Local Address . . . . . . . . . . . . . 28 107 6.2.14. Multipath Transport . . . . . . . . . . . . . . . . . 28 108 6.2.15. Advertisement of Alternative Addresses . . . . . . . 29 109 6.2.16. Direction of communication . . . . . . . . . . . . . 30 110 6.2.17. Notification of ICMP soft error message arrival . . . 30 111 6.2.18. Initiating side is not the first to write . . . . . . 31 112 6.3. Specifying Security Parameters and Callbacks . . . . . . 31 113 6.3.1. Specifying Security Parameters on a Pre-Connection . 31 114 6.3.2. Connection Establishment Callbacks . . . . . . . . . 33 115 7. Establishing Connections . . . . . . . . . . . . . . . . . . 33 116 7.1. Active Open: Initiate . . . . . . . . . . . . . . . . . . 34 117 7.2. Passive Open: Listen . . . . . . . . . . . . . . . . . . 35 118 7.3. Peer-to-Peer Establishment: Rendezvous . . . . . . . . . 36 119 7.4. Connection Groups . . . . . . . . . . . . . . . . . . . . 38 120 8. Managing Connections . . . . . . . . . . . . . . . . . . . . 39 121 8.1. Generic Connection Properties . . . . . . . . . . . . . . 41 122 8.1.1. Required Minimum Corruption Protection Coverage for 123 Receiving . . . . . . . . . . . . . . . . . . . . . . 41 124 8.1.2. Connection Priority . . . . . . . . . . . . . . . . . 42 125 8.1.3. Timeout for Aborting Connection . . . . . . . . . . . 42 126 8.1.4. Timeout for keep alive packets . . . . . . . . . . . 42 127 8.1.5. Connection Group Transmission Scheduler . . . . . . . 43 128 8.1.6. Capacity Profile . . . . . . . . . . . . . . . . . . 43 129 8.1.7. Policy for using Multipath Transports . . . . . . . . 45 130 8.1.8. Bounds on Send or Receive Rate . . . . . . . . . . . 46 131 8.1.9. Group Connection Limit . . . . . . . . . . . . . . . 46 132 8.1.10. Isolate Session . . . . . . . . . . . . . . . . . . . 46 133 8.1.11. Read-only Connection Properties . . . . . . . . . . . 47 134 8.2. TCP-specific Properties: User Timeout Option (UTO) . . . 48 135 8.2.1. Advertised User Timeout . . . . . . . . . . . . . . . 48 136 8.2.2. User Timeout Enabled . . . . . . . . . . . . . . . . 48 137 8.2.3. Timeout Changeable . . . . . . . . . . . . . . . . . 49 138 8.3. Connection Lifecycle Events . . . . . . . . . . . . . . . 49 139 8.3.1. Soft Errors . . . . . . . . . . . . . . . . . . . . . 49 140 8.3.2. Path change . . . . . . . . . . . . . . . . . . . . . 49 141 9. Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . 49 142 9.1. Messages and Framers . . . . . . . . . . . . . . . . . . 50 143 9.1.1. Message Contexts . . . . . . . . . . . . . . . . . . 50 144 9.1.2. Message Framers . . . . . . . . . . . . . . . . . . . 50 145 9.1.3. Message Properties . . . . . . . . . . . . . . . . . 53 146 9.2. Sending Data . . . . . . . . . . . . . . . . . . . . . . 58 147 9.2.1. Basic Sending . . . . . . . . . . . . . . . . . . . . 59 148 9.2.2. Send Events . . . . . . . . . . . . . . . . . . . . . 59 149 9.2.3. Partial Sends . . . . . . . . . . . . . . . . . . . . 60 150 9.2.4. Batching Sends . . . . . . . . . . . . . . . . . . . 61 151 9.2.5. Send on Active Open: InitiateWithSend . . . . . . . . 61 152 9.2.6. Priority in TAPS . . . . . . . . . . . . . . . . . . 62 153 9.3. Receiving Data . . . . . . . . . . . . . . . . . . . . . 63 154 9.3.1. Enqueuing Receives . . . . . . . . . . . . . . . . . 63 155 9.3.2. Receive Events . . . . . . . . . . . . . . . . . . . 64 156 9.3.3. Receive Message Properties . . . . . . . . . . . . . 66 157 10. Connection Termination . . . . . . . . . . . . . . . . . . . 67 158 11. Connection State and Ordering of Operations and Events . . . 69 159 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 70 160 13. Privacy and Security Considerations . . . . . . . . . . . . . 70 161 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 72 162 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 72 163 15.1. Normative References . . . . . . . . . . . . . . . . . . 72 164 15.2. Informative References . . . . . . . . . . . . . . . . . 73 165 Appendix A. Implementation Mapping . . . . . . . . . . . . . . . 76 166 A.1. Types . . . . . . . . . . . . . . . . . . . . . . . . . . 76 167 A.2. Events and Errors . . . . . . . . . . . . . . . . . . . . 77 168 A.3. Time Duration . . . . . . . . . . . . . . . . . . . . . . 77 169 Appendix B. Convenience Functions . . . . . . . . . . . . . . . 77 170 B.1. Adding Preference Properties . . . . . . . . . . . . . . 77 171 B.2. Transport Property Profiles . . . . . . . . . . . . . . . 78 172 B.2.1. reliable-inorder-stream . . . . . . . . . . . . . . . 78 173 B.2.2. reliable-message . . . . . . . . . . . . . . . . . . 78 174 B.2.3. unreliable-datagram . . . . . . . . . . . . . . . . . 79 175 Appendix C. Relationship to the Minimal Set of Transport Services 176 for End Systems . . . . . . . . . . . . . . . . . . . . . 80 177 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 83 179 1. Introduction 181 This document specifies a modern abstract application programming 182 interface (API) atop the high-level architecture for transport 183 services defined in [I-D.ietf-taps-arch]. The Transport Services 184 Architecture supports asynchronous, atomic transmission of messages 185 over transport protocols and network paths dynamically selected at 186 runtime, in environments where an endpoint selects from multiple 187 interfaces and potential transport protocols. 189 Applications that adopt this interface will benefit from a wide set 190 of transport features that can evolve over time. This protocol- 191 independent API ensures that the system providing the interface can 192 optimize its behavior based on the application requirements and 193 network conditions, without requiring changes to the applications. 194 This flexibility enables faster deployment of new features and 195 protocols, and can support applications by offering racing and 196 fallback mechanisms, which otherwise need to be separately 197 implemented in each application. 199 This API derives specific path and protocol selection properties and 200 supported transport features from the analysis provided in [RFC8095], 201 [RFC8923], and [RFC8922]. The design encourages implementations 202 underneath the interface to dynamically choose a transport protocol 203 depending on an application's choices rather than statically binding 204 applications to a protocol at compile time. Nevertheless, the 205 Transport Services API also provides applications with a way to 206 override transport selection and instantiate a specific stack, e.g., 207 to support servers wishing to listen to a specific protocol. 208 However, forcing a specific transport stack choice is discouraged for 209 general use, because it can reduce portability. 211 1.1. Terminology and Notation 213 This API is described in terms of 215 * Objects with which an application can interact; 217 * Actions the application can perform on these Objects; 219 * Events, which an Object can send to an application to be processed 220 aynchronously; and 222 * Parameters associated with these Actions and Events. 224 The following notations, which can be combined, are used in this 225 document: 227 * An Action that creates an Object: 229 Object := Action() 231 * An Action that creates an array of Objects: 233 []Object := Action() 235 * An Action that is performed on an Object: 237 Object.Action() 239 * An Object sends an Event: 241 Object -> Event<> 243 * An Action takes a set of Parameters; an Event contains a set of 244 Parameters. Action and Event parameters whose names are suffixed 245 with a question mark are optional. 247 Action(param0, param1?, ...) / Event 249 Actions associated with no Object are Actions on the abstract 250 interface itself; they are equivalent to Actions on a per-application 251 global context. 253 Events are sent to the application or application-supplied code (e.g. 254 framers, see Section 9.1.2) for processing; the details of event 255 processing are platform- and implementation-specific. 257 We also make use of the following basic types: 259 * Boolean: Instances take the value "true" or "false". 261 * Integer: Instances take positive or negative numeric integer 262 values, or sometimes special non-numeric (symbolic) values. 264 * Numeric: Instances take positive or negative numeric values, or 265 sometimes special non-numeric (symbolic) 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 Interface Design 297 The design of the interface specified in this document is based on a 298 set of principles, themselves an elaboration on the architectural 299 design principles defined in [I-D.ietf-taps-arch]. The interface 300 defined in this document provides: 302 * Access to a variety of transport protocols, independent of the 303 Protocol Stacks that will be used at runtime. All common features 304 of these protocol stacks are made available to the application in 305 a transport-independent way to the degree possible. This enables 306 applications written to a single API to make use of transport 307 protocols in terms of the features they provide. 309 * A unified interface to datagram and stream-oriented transports, 310 allowing use of a common API for connection establishment and 311 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, in line with developments in modern platforms and 321 programming languages; 323 * Selection between alternate network paths, using additional 324 information about the networks over which a connection can operate 325 (e.g. Provisioning Domain (PvD) information [RFC7556]) where 326 available. 328 * Explicit support for transport-specific features to be applied, 329 should that particular transport be part of a chosen Protocol 330 Stack. 332 * Explicit support for security properties as first-order transport 333 features. 335 * Explicit support for configuration of cryptographic identities and 336 transport security parameters persistent across multiple 337 Connections. 339 * Explicit support for multistreaming and multipath transport 340 protocols, and the grouping of related Connections into Connection 341 Groups through cloning of Connections. This allows applications 342 to take full advantage of new transport protocols supporting these 343 features. 345 3. API Summary 347 The Transport Services API is the basic common abstract application 348 programming interface to the Transport Services Architecture defined 349 in the TAPS Architecture [I-D.ietf-taps-arch]. 351 An application primarily interacts with this API through two Objects: 352 Preconnections and Connections. A Preconnection object (Section 6) 353 represents a set of properties and constraints on the selection and 354 configuration of paths and protocols to establish a Connection with 355 an Endpoint. A Connection object represents an instance of a 356 transport Protocol Stack on which data can be sent to and/or received 357 from a Remote Endpoint (i.e., a logical connection that, depending on 358 the kind of transport, can be bi-directional or unidirectional, and 359 that can use a stream protocol or a datagram protocol). Connections 360 are presented consistently to the application, irrespective of 361 whether the underlying transport is connection-less or connection- 362 oriented. Connections can be created from Preconnections in three 363 ways: 365 * by initiating the Preconnection (i.e., actively opening, as in a 366 client; Section 7.1), 368 * through listening on the Preconnection (i.e., passively opening, 369 as in a server Section 7.2), 371 * or rendezvousing on the Preconnection (i.e., peer to peer 372 establishment; Section 7.3). 374 Once a Connection is established, data can be sent and received on it 375 in the form of Messages. The interface supports the preservation of 376 message boundaries both via explicit Protocol Stack support, and via 377 application support through a Message Framer that finds message 378 boundaries in a stream. Messages are received asynchronously through 379 event handlers registered by the application. Errors and other 380 notifications also happen asynchronously on the Connection. It is 381 not necessary for an application to handle all Events; some Events 382 may have implementation-specific default handlers. The application 383 should not assume that ignoring Events (e.g., Errors) is always safe. 385 Section 6, Section 7, Section 9.2, Section 9.3, and Section 10 386 describe the details of application interaction with Objects through 387 Actions and Events in each phase of a Connection, following the 388 phases (Pre-Establishment, Establishment, Data Transfer, and 389 Termination) described in Section 4.1 of [I-D.ietf-taps-arch]. 391 3.1. Usage Examples 393 The following usage examples illustrate how an application might use 394 the Transport Services Interface to: 396 * Act as a server, by listening for incoming connections, receiving 397 requests, and sending responses, see Section 3.1.1. 399 * Act as a client, by connecting to a Remote Endpoint using 400 Initiate, sending requests, and receiving responses, see 401 Section 3.1.2. 403 * Act as a peer, by connecting to a Remote Endpoint using Rendezvous 404 while simultaneously waiting for incoming Connections, sending 405 Messages, and receiving Messages, see Section 3.1.3. 407 The examples in this section presume that a transport protocol is 408 available between the Local and Remote Endpoints that provides 409 Reliable Data Transfer, Preservation of data ordering, and 410 Preservation of Message Boundaries. In this case, the application 411 can choose to receive only complete messages. 413 If none of the available transport protocols provides Preservation of 414 Message Boundaries, but there is a transport protocol that provides a 415 reliable ordered byte stream, an application could receive this byte 416 stream as partial Messages and transform it into application-layer 417 Messages. Alternatively, an application might provide a Message 418 Framer, which can transform a sequence of Messages into a byte stream 419 and vice versa (Section 9.1.2). 421 3.1.1. Server Example 423 This is an example of how an application might listen for incoming 424 Connections using the Transport Services Interface, and receive a 425 request, and send a response. 427 LocalSpecifier := NewLocalEndpoint() 428 LocalSpecifier.WithInterface("any") 429 LocalSpecifier.WithService("https") 431 TransportProperties := NewTransportProperties() 432 TransportProperties.Require(preserve-msg-boundaries) 433 // Reliable Data Transfer and Preserve Order are Required by default 435 SecurityParameters := NewSecurityParameters() 436 SecurityParameters.Set(identity, myIdentity) 437 SecurityParameters.Set(key-pair, myPrivateKey, myPublicKey) 439 // Specifying a Remote Endpoint is optional when using Listen() 440 Preconnection := NewPreconnection(LocalSpecifier, 441 TransportProperties, 442 SecurityParameters) 444 Listener := Preconnection.Listen() 446 Listener -> ConnectionReceived 448 // Only receive complete messages in a Conn.Received handler 449 Connection.Receive() 451 Connection -> Received 453 //---- Receive event handler begin ---- 454 Connection.Send(messageDataResponse) 455 Connection.Close() 457 // Stop listening for incoming Connections 458 // (this example supports only one Connection) 459 Listener.Stop() 460 //---- Receive event handler end ---- 462 3.1.2. Client Example 464 This is an example of how an application might open two Connections 465 to a remote application using the Transport Services Interface, and 466 send a request as well as receive a response on each of them. 468 RemoteSpecifier := NewRemoteEndpoint() 469 RemoteSpecifier.WithHostname("example.com") 470 RemoteSpecifier.WithService("https") 472 TransportProperties := NewTransportProperties() 473 TransportProperties.Require(preserve-msg-boundaries) 474 // Reliable Data Transfer and Preserve Order are Required by default 476 SecurityParameters := NewSecurityParameters() 477 TrustCallback := NewCallback({ 478 // Verify identity of the Remote Endpoint, return the result 479 }) 480 SecurityParameters.SetTrustVerificationCallback(TrustCallback) 482 // Specifying a local endpoint is optional when using Initiate() 483 Preconnection := NewPreconnection(RemoteSpecifier, 484 TransportProperties, 485 SecurityParameters) 487 Connection := Preconnection.Initiate() 488 Connection2 := Connection.Clone() 490 Connection -> Ready<> 491 Connection2 -> Ready<> 493 //---- Ready event handler for any Connection C begin ---- 494 C.Send(messageDataRequest) 496 // Only receive complete messages 497 C.Receive() 498 //---- Ready event handler for any Connection C end ---- 500 Connection -> Received 501 Connection2 -> Received 503 // Close the Connection in a Receive event handler 504 Connection.Close() 505 Connection2.Close() 507 Preconnections are reusable after being used to initiate a 508 Connection. Hence, for example, after the Connections were closed, 509 the following would be correct: ~~~ //.. carry out adjustments to the 510 Preconnection, if desire Connection := Preconnection.Initiate() ~~~ 512 3.1.3. Peer Example 514 This is an example of how an application might establish a connection 515 with a peer using Rendezvous(), send a Message, and receive a 516 Message. 518 // Configure local candidates: a port on the Local Endpoint and via a STUN server 519 HostCandidate := NewLocalEndpoint() 520 HostCandidate.WithPort(9876) 522 StunCandidate := NewLocalEndpoint() 523 StunCandidate.WithStunServer(address, port, credentials) 525 LocalCandidates = [HostCandidate, StunCandidate] 527 // Configure transport and security properties 528 TransportProperties := ... 529 SecurityParameters := ... 531 Preconnection := NewPreconnection(LocalCandidates, 532 [], // No remote candidates yet 533 TransportProperties, 534 SecurityParameters) 536 // Resolve the LocalCandidates. The Preconnection.Resolve() call 537 // resolves both local and remote candidates but, since the remote 538 // candidates have not yet been specified, the ResolvedRemote list 539 // returned will be empty and is not used. 540 ResolvedLocal, ResolvedRemote = Preconnection.Resolve() 542 // ...Send the ResolvedLocal list to peer via signalling channel 543 // ...Receive a list of RemoteCandidates from peer via signalling channel 545 Preconnection.AddRemote(RemoteCandidates) 546 Preconnection.Rendezvous() 548 Preconnection -> RendezvousDone 550 //---- RendezvousDone event handler begin ---- 551 Connection.Send(messageDataRequest) 552 Connection.Receive() 553 //---- RendezvousDone event handler end ---- 555 Connection -> Received 557 // Close the Connection in a Receive event handler 558 Connection.Close() 559 4. Transport Properties 561 Each application using the Transport Services Interface declares its 562 preferences for how the transport service should operate using 563 properties at each stage of the lifetime of a connection using 564 Transport Properties, as defined in [I-D.ietf-taps-arch]. 566 Transport Properties are divided into Selection, Connection, and 567 Message Properties. Selection Properties (see Section 6.2) can only 568 be set during pre-establishment. They are only used to specify which 569 paths and protocol stacks can be used and are preferred by the 570 application. Although Connection Properties (see Section 8.1) can be 571 set during pre-establishment, they may be changed later. They are 572 used to inform decisions made during establishment and to fine-tune 573 the established connection. Calling Initiate on a Preconnection 574 creates an outbound Connection or a Listener, and the Selection 575 Properties remain readable from the Connection or Listener, but 576 become immutable. 578 The behavior of the selected protocol stack(s) when sending Messages 579 is controlled by Message Properties (see Section 9.1.3). 581 Selection Properties can be set on Preconnections, and the effect of 582 Selection Properties can be queried on Connections and Messages. 583 Connection Properties can be set on Connections and Preconnections; 584 when set on Preconnections, they act as an initial default for the 585 resulting Connections. Message Properties can be set on Messages, 586 Connections, and Preconnections; when set on the latter two, they act 587 as an initial default for the Messages sent over those Connections, 589 Note that configuring Connection Properties and Message Properties on 590 Preconnections is preferred over setting them later. Early 591 specification of Connection Properties allows their use as additional 592 input to the selection process. Protocol Specific Properties, which 593 enable configuration of specialized features of a specific protocol, 594 see Section 3.2 of [I-D.ietf-taps-arch], are not used as an input to 595 the selection process, but only support configuration if the 596 respective protocol has been selected. 598 4.1. Transport Property Names 600 Transport Properties are referred to by property names. For the 601 purposes of this document, these names are alphanumeric strings in 602 which words may be separated by hyphens. These names serve two 603 purposes: 605 * Allowing different components of a TAPS implementation to pass 606 Transport Properties, e.g., between a language frontend and a 607 policy manager, or as a representation of properties retrieved 608 from a file or other storage. 610 * Making the code of different TAPS implementations look similar. 611 While individual programming languages may preclude strict 612 adherence to the aforementioned naming convention (for instance, 613 by prohibiting the use of hyphens in symbols), users interacting 614 with multiple implementations will still benefit from the 615 consistency resulting from the use of visually similar symbols. 617 Transport Property Names are hierarchically organized in the form 618 [.]. 620 * The Namespace component MUST be empty for well-known, generic 621 properties, i.e., for properties that are not specific to a 622 protocol and are defined in an RFC. 624 * Protocol Specific Properties MUST use the protocol acronym as the 625 Namespace, e.g., "tcp" for TCP specific Transport Properties. For 626 IETF protocols, property names under these namespaces SHOULD be 627 defined in an RFC. 629 * Vendor or implementation specific properties MUST use a string 630 identifying the vendor or implementation as the Namespace. 632 Namespaces for each of the keywords provided in the IANA protocol 633 numbers registry (see https://www.iana.org/assignments/protocol- 634 numbers/protocol-numbers.xhtml), reformatted where necessary to 635 conform to an implementation's naming conventions, are reserved for 636 Protocol Specific Properties and MUST NOT be used for vendor or 637 implementation-specific properties. 639 4.2. Transport Property Types 641 Each Transport Property has a one of the basic types described in 642 Section 1.1. 644 Most Selection Properties (see Section 6.2) are of the Enumeration 645 type, and use the Preference Enumeration, which takes one of five 646 possible values (Prohibit, Avoid, Ignore, Prefer, or Require) 647 denoting the level of preference for a given property during protocol 648 selection. 650 5. Scope of the Interface Definition 652 This document defines a language- and platform-independent interface 653 to a Transport Services system. Given the wide variety of languages 654 and language conventions used to write applications that use the 655 transport layer to connect to other applications over the Internet, 656 this independence makes this interface necessarily abstract. 658 There is no interoperability benefit in tightly defining how the 659 interface is presented to application programmers across diverse 660 platforms. However, maintaining the "shape" of the abstract 661 interface across different platforms reduces the effort for 662 programmers who learn the transport services interface to then apply 663 their knowledge to another platform. 665 We therefore make the following recommendations: 667 * Actions, Events, and Errors in implementations of this interface 668 SHOULD use the names given for them in the document, subject to 669 capitalization, punctuation, and other typographic conventions in 670 the language of the implementation, unless the implementation 671 itself uses different names for substantially equivalent objects 672 for networking by convention. 674 * Implementations of this interface SHOULD implement each Selection 675 Property, Connection Property, and Message Context Property 676 specified in this document. Each interface SHOULD be implemented 677 even when in a specific implementation/platform it will always 678 result in no operation, e.g. there is no action when the API 679 specifies a Property that is not available in a transport protocol 680 implemented on a specific platform. For example, if TCP is the 681 only underlying transport protocol, the Message Property 682 "msgOrdered" can be implemented (trivially, as a no-op) as 683 disabling the requirement for ordering will not have any effect on 684 delivery order for Connections over TCP. Similarly, the "msg- 685 lifetime" Message Property can be implemented but ignored, as the 686 description of this Property states that "it is not guaranteed 687 that a Message will not be sent when its Lifetime has expired". 689 * Implementations may use other representations for Transport 690 Property Names, e.g., by providing constants, but should provide a 691 straight-forward mapping between their representation and the 692 property names specified here. 694 6. Pre-Establishment Phase 696 The Pre-Establishment phase allows applications to specify properties 697 for the Connections that they are about to make, or to query the API 698 about potential Connections they could make. 700 A Preconnection Object represents a potential Connection. It is a 701 passive Object (a data structure) that merely maintains the state 702 that describes the properties of a Connection that might exist in the 703 future. This state comprises Local Endpoint and Remote Endpoint 704 Objects that denote the endpoints of the potential Connection (see 705 Section 6.1), the Selection Properties (see Section 6.2), any 706 preconfigured Connection Properties (Section 8.1), and the security 707 parameters (see Section 6.3): 709 Preconnection := NewPreconnection([]LocalEndpoint, 710 []RemoteEndpoint, 711 TransportProperties, 712 SecurityParameters) 714 At least one Local Endpoint MUST be specified if the Preconnection is 715 used to Listen() for incoming Connections, but the list of Local 716 Endpoints MAY be empty if the Preconnection is used to Initiate() 717 connections. If no Local Endpoint is specified, the Transport 718 Services system will assign an ephemeral local port to the Connection 719 on the appropriate interface(s). At least one Remote Endpoint MUST 720 be specified if the Preconnection is used to Initiate() Connections, 721 but the list of Remote Endpoints MAY be empty if the Preconnection is 722 used to Listen() for incoming Connections. At least one Local 723 Endpoint and one Remote Endpoint MUST be specified if a peer-to-peer 724 Rendezvous() is to occur based on the Preconnection. 726 If more than one Local Endpoint is specified on a Preconnection, then 727 all the Local Endpoints on the Preconnection MUST represent the same 728 host. For example, they might correspond to different interfaces on 729 a multi-homed host, of they might correspond to local interfaces and 730 a STUN server that can be resolved to a server reflexive address for 731 a Preconnection used to make a peer-to-peer Rendezvous(). 733 If more than one Remote Endpoint is specified on the Preconnection, 734 then all the Remote Endpoints on the Preconnection SHOULD represent 735 the same host. For example, the Remote Endpoints might represent 736 various network interfaces of a host, or a server reflexive address 737 that can be used to reach a host, or a set of hosts that provide 738 equivalent local balanced service. 740 In most cases, it is expected that a single Remote Endpoint will be 741 specified by name, and a later call to Initiate() on the 742 Preconnection (see Section 7.1) will internally resolve that name to 743 a list of concrete endpoints. Specifying multiple Remote Endpoints 744 on a Preconnection allows applications to override this for more 745 detailed control. 747 If Message Framers are used (see Section 9.1.2), they MUST be added 748 to the Preconnection during pre-establishment. 750 6.1. Specifying Endpoints 752 The transport services API uses the Local Endpoint and Remote 753 Endpoint Objects to refer to the endpoints of a transport connection. 754 Endpoints can be created as either Remote or Local: 756 RemoteSpecifier := NewRemoteEndpoint() 757 LocalSpecifier := NewLocalEndpoint() 759 A single Endpoint Object represents the identity of a network host. 760 That endpoint can be more or less specific depending on which 761 identifiers are set. For example, an Endpoint that only specifies a 762 hostname may in fact end up corresponding to several different IP 763 addresses on different hosts. 765 An Endpoint Object can be configured with the following identifiers: 767 * Hostname (string): 769 RemoteSpecifier.WithHostname("example.com") 771 * Port (a 16-bit integer) or a Service (string) that maps to a port: 773 RemoteSpecifier.WithPort(443) 775 RemoteSpecifier.WithService("https") 777 * IP address (IPv4 or IPv6 address): 779 RemoteSpecifier.WithIPv4Address(192.0.2.21) 781 RemoteSpecifier.WithIPv6Address(2001:db8:4920:e29d:a420:7461:7073:0a) 783 * Interface name (string): 785 LocalSpecifier.WithInterface("en0") 786 An Endpoint cannot have multiple identifiers of a same type set. 787 That is, an endpoint cannot have two IP addresses specified. Two 788 separate IP addresses are represented as two Endpoint Objects. If a 789 Preconnection specifies a Remote Endpoint with a specific IP address 790 set, it will only establish Connections to that IP address. If, on 791 the other hand, the Remote Endpoint specifies a hostname but no 792 addresses, the Connection can perform name resolution and attempt 793 using any address derived from the original hostname of the Remote 794 Endpoint. 796 The Transport Services API resolves names internally, when the 797 Initiate(), Listen(), or Rendezvous() method is called to establish a 798 Connection. Privacy considerations for the timing of this resolution 799 are given in Section 13. 801 The Resolve() action on a Preconnection can be used by the 802 application to force early binding when required, for example with 803 some Network Address Translator (NAT) traversal protocols (see 804 Section 7.3). 806 6.1.1. Using Multicast Endpoints 808 Specifying a multicast group address on a Local Endpoint will 809 indicate to the transport system that the resulting connection will 810 be used to receive multicast messages. The Remote Endpoint can be 811 used to filter incoming multicast from specific senders. Such a 812 Preconnection will only support calling Listen(), not Initiate(). 813 The accepted Connections are receive-only. 815 Similarly, specifying a multicast group address on the Remote 816 Endpoint will indicate that the resulting connection will be used to 817 send multicast messages. 819 6.1.2. Endpoint Aliases 821 An Endpoint can have an alternative definition when using different 822 protocols. For example, a server that supports both TLS/TCP and QUIC 823 may be accessible on two different port numbers depending on which 824 protocol is used. 826 To support this, Endpoint Objects can specify "aliases". An Endpoint 827 can have multiple aliases set. 829 RemoteSpecifier.AddAlias(AlternateRemoteSpecifier) 831 In order to scope an alias to a specific transport protocol, an 832 Endpoint can specify a protocol identifier. 834 RemoteSpecifier.WithProtocol(QUIC) 836 The following example shows a case where "example.com" has a server 837 running on port 443, with an alternate port of 8443 for QUIC. 839 RemoteSpecifier := NewRemoteEndpoint() 840 RemoteSpecifier.WithHostname("example.com") 841 RemoteSpecifier.WithPort(443) 843 QUICRemoteSpecifier := NewRemoteEndpoint() 844 QUICRemoteSpecifier.WithHostname("example.com") 845 QUICRemoteSpecifier.WithPort(8443) 846 QUICRemoteSpecifier.WithProtocol(QUIC) 848 RemoteSpecifier.AddAlias(QUICRemoteSpecifier) 850 6.1.3. Endpoint Examples 852 The following examples of Endpoints show common usage patterns. 854 Specify a Remote Endpoint using a hostname and service name: 856 RemoteSpecifier := NewRemoteEndpoint() 857 RemoteSpecifier.WithHostname("example.com") 858 RemoteSpecifier.WithService("https") 860 Specify a Remote Endpoint using an IPv6 address and remote port: 862 RemoteSpecifier := NewRemoteEndpoint() 863 RemoteSpecifier.WithIPv6Address(2001:db8:4920:e29d:a420:7461:7073:0a) 864 RemoteSpecifier.WithPort(443) 866 Specify a Remote Endpoint using an IPv4 address and remote port: 868 RemoteSpecifier := NewRemoteEndpoint() 869 RemoteSpecifier.WithIPv4Address(192.0.2.21) 870 RemoteSpecifier.WithPort(443) 872 Specify a Local Endpoint using a local interface name and local port: 874 LocalSpecifier := NewLocalEndpoint() 875 LocalSpecifier.WithInterface("en0") 876 LocalSpecifier.WithPort(443) 878 As an alternative to specifying an interface name for the Local 879 Endpoint, an application can express more fine-grained preferences 880 using the "Interface Instance or Type" Selection Property, see 881 Section 6.2.11. However, if the application specifies Selection 882 Properties that are inconsistent with the Local Endpoint, this will 883 result in an Error once the application attempts to open a 884 Connection. 886 Specify a Local Endpoint using a STUN server: 888 LocalSpecifier := NewLocalEndpoint() 889 LocalSpecifier.WithStunServer(address, port, credentials) 891 Specify a Local Endpoint using an Any-Source Multicast group to join 892 on a named local interface: 894 LocalSpecifier := NewLocalEndpoint() 895 LocalSpecifier.WithIPv4Address(233.252.0.0) 896 LocalSpecifier.WithInterface("en0") 898 Source-Specific Multicast requires setting both a Local and Remote 899 Endpoint: 901 LocalSpecifier := NewLocalEndpoint() 902 LocalSpecifier.WithIPv4Address(232.1.1.1) 903 LocalSpecifier.WithInterface("en0") 905 RemoteSpecifier := NewRemoteEndpoint() 906 RemoteSpecifier.WithIPv4Address(192.0.2.22) 908 6.2. Specifying Transport Properties 910 A Preconnection Object holds properties reflecting the application's 911 requirements and preferences for the transport. These include 912 Selection Properties for selecting protocol stacks and paths, as well 913 as Connection Properties for configuration of the detailed operation 914 of the selected Protocol Stacks. 916 The protocol(s) and path(s) selected as candidates during 917 establishment are determined and configured using these properties. 918 Since there could be paths over which some transport protocols are 919 unable to operate, or remote endpoints that support only specific 920 network addresses or transports, transport protocol selection is 921 necessarily tied to path selection. This may involve choosing 922 between multiple local interfaces that are connected to different 923 access networks. 925 When additional information (such as Provisioning Domain (PvD) 926 information Path information can include network segment PMTU, set of 927 supported DSCPs, expected usage, cost, etc. The usage of this 928 information by the Transport Services System is generally independent 929 of the specific mechanism/protocol used to receive the information 930 (e.g. zero-conf, DHCP, or IPv6 RA).[RFC7556]) is available about the 931 networks over which an endpoint can operate, this can inform the 932 selection between alternate network paths. 934 Most Selection Properties are represented as Preferences, which can 935 take one of five values: 937 +============+========================================+ 938 | Preference | Effect | 939 +============+========================================+ 940 | Require | Select only protocols/paths providing | 941 | | the property, fail otherwise | 942 +------------+----------------------------------------+ 943 | Prefer | Prefer protocols/paths providing the | 944 | | property, proceed otherwise | 945 +------------+----------------------------------------+ 946 | Ignore | No preference | 947 +------------+----------------------------------------+ 948 | Avoid | Prefer protocols/paths not providing | 949 | | the property, proceed otherwise | 950 +------------+----------------------------------------+ 951 | Prohibit | Select only protocols/paths not | 952 | | providing the property, fail otherwise | 953 +------------+----------------------------------------+ 955 Table 1: Selection Property Preference Levels 957 The implementation MUST ensure an outcome that is consistent with all 958 application requirements expressed using Require and Prohibit. While 959 preferences expressed using Prefer and Avoid influence protocol and 960 path selection as well, outcomes can vary given the same Selection 961 Properties, because the available protocols and paths can differ 962 across systems and contexts. However, implementations are 963 RECOMMENDED to seek to provide a consistent outcome to an 964 application, given the same set of Selection Properties. 966 Note that application preferences can conflict with each other. For 967 example, if an application indicates a preference for a specific path 968 by specifying an interface, but also a preference for a protocol, a 969 situation might occur in which the preferred protocol is not 970 available on the preferred path. In such cases, applications can 971 expect properties that determine path selection to be prioritized 972 over properties that determine protocol selection. The transport 973 system SHOULD determine the preferred path first, regardless of 974 protocol preferences. This ordering is chosen to provide consistency 975 across implementations, based on the fact that it is more common for 976 the use of a given network path to determine cost to the user (i.e., 977 an interface type preference might be based on a user's preference to 978 avoid being charged more for a cellular data plan). 980 Selection and Connection Properties, as well as defaults for Message 981 Properties, can be added to a Preconnection to configure the 982 selection process and to further configure the eventually selected 983 protocol stack(s). They are collected into a TransportProperties 984 object to be passed into a Preconnection object: 986 TransportProperties := NewTransportProperties() 988 Individual properties are then set on the TransportProperties Object. 989 Setting a Transport Property to a value overrides the previous value 990 of this Transport Property. 992 TransportProperties.Set(property, value) 994 To aid readability, implementations MAY provide additional 995 convenience functions to simplify use of Selection Properties: see 996 Appendix B.1 for examples. In addition, implementations MAY provide 997 a mechanism to create TransportProperties objects that are 998 preconfigured for common use cases as outlined in Appendix B.2. 1000 Transport Properties for an established connection can be queried via 1001 the Connection object, as outlined in Section 8. 1003 A Connection gets its Transport Properties either by being explicitly 1004 configured via a Preconnection, by configuration after establishment, 1005 or by inheriting them from an antecedent via cloning; see Section 7.4 1006 for more. 1008 Section 8.1 provides a list of Connection Properties, while Selection 1009 Properties are listed in the subsections below. Many properties are 1010 only considered during establishment, and can not be changed after a 1011 Connection is established; however, they can still be queried. The 1012 return type of a queried Selection Property is Boolean, where "true" 1013 means that the Selection Property has been applied and "false" means 1014 that the Selection Property has not been applied. Note that "true" 1015 does not mean that a request has been honored. For example, if 1016 "Congestion control" was requested with preference level "Prefer", 1017 but congestion control could not be supported, querying the 1018 "congestionControl" property yields the value "false". If the 1019 preference level "Avoid" was used for "Congestion control", and, as 1020 requested, the Connection is not congestion controlled, querying the 1021 "congestionControl" property also yields the value "false". 1023 An implementation of this interface must provide sensible defaults 1024 for Selection Properties. The default values for each property below 1025 represent a configuration that can be implemented over TCP. If these 1026 default values are used and TCP is not supported by a Transport 1027 Services implementation, then an application using the default set of 1028 Properties might not succeed in establishing a connection. Using the 1029 same default values for independent Transport Services 1030 implementations can be beneficial when applications are ported 1031 between different implementations/platforms, even if this default 1032 could lead to a connection failure when TCP is not available. If 1033 default values other than those suggested below are used, it is 1034 RECOMMENDED to clearly document any differences. 1036 6.2.1. Reliable Data Transfer (Connection) 1038 Name: reliability 1040 Type: Preference 1042 Default: Require 1044 This property specifies whether the application needs to use a 1045 transport protocol that ensures that all data is received at the 1046 Remote Endpoint without corruption. When reliable data transfer is 1047 enabled, this also entails being notified when a Connection is closed 1048 or aborted. 1050 6.2.2. Preservation of Message Boundaries 1052 Name: preserveMsgBoundaries 1054 Type: Preference 1056 Default: Ignore 1058 This property specifies whether the application needs or prefers to 1059 use a transport protocol that preserves message boundaries. 1061 6.2.3. Configure Per-Message Reliability 1063 Name: perMsgReliability 1065 Type: Preference 1067 Default: Ignore 1069 This property specifies whether an application considers it useful to 1070 specify different reliability requirements for individual Messages in 1071 a Connection. 1073 6.2.4. Preservation of Data Ordering 1075 Name: preserveOrder 1077 Type: Preference 1079 Default: Require 1081 This property specifies whether the application wishes to use a 1082 transport protocol that can ensure that data is received by the 1083 application on the other end in the same order as it was sent. 1085 6.2.5. Use 0-RTT Session Establishment with a Safely Replayable Message 1087 Name: zeroRttMsg 1089 Type: Preference 1091 Default: Ignore 1093 This property specifies whether an application would like to supply a 1094 Message to the transport protocol before Connection establishment 1095 that will then be reliably transferred to the other side before or 1096 during Connection establishment. This Message can potentially be 1097 received multiple times (i.e., multiple copies of the message data 1098 may be passed to the Remote Endpoint). See also Section 9.1.3.4. 1100 6.2.6. Multistream Connections in Group 1102 Name: multistreaming 1104 Type: Preference 1106 Default: Prefer 1107 This property specifies that the application would prefer multiple 1108 Connections within a Connection Group to be provided by streams of a 1109 single underlying transport connection where possible. 1111 6.2.7. Full Checksum Coverage on Sending 1113 Name: FullChecksumSend 1115 Type: Preference 1117 Default: Require 1119 This property specifies the application's need for protection against 1120 corruption for all data transmitted on this Connection. Disabling 1121 this property could enable later control of the sender checksum 1122 coverage (see Section 9.1.3.6). 1124 6.2.8. Full Checksum Coverage on Receiving 1126 Name: FullChecksumRecv 1128 Type: Preference 1130 Default: Require 1132 This property specifies the application's need for protection against 1133 corruption for all data received on this Connection. Disabling this 1134 property could enable later control of the required minimum receiver 1135 checksum coverage (see Section 8.1.1). 1137 6.2.9. Congestion control 1139 Name: congestionControl 1141 Type: Preference 1143 Default: Require 1144 This property specifies whether the application would like the 1145 Connection to be congestion controlled or not. Note that if a 1146 Connection is not congestion controlled, an application using such a 1147 Connection SHOULD itself perform congestion control in accordance 1148 with [RFC2914] or use a circuit breaker in accordance with [RFC8084], 1149 whichever is appropriate. Also note that reliability is usually 1150 combined with congestion control in protocol implementations, 1151 rendering "reliable but not congestion controlled" a request that is 1152 unlikely to succeed. If the Connection is congestion controlled, 1153 performing additional congestion control in the application can have 1154 negative performance implications. 1156 6.2.10. Keep alive 1158 Name: keepAlive 1160 Type: Preference 1162 Default: Ignore 1164 This property specifies whether the application would like the 1165 Connection to send keep-alive packets or not. Note that if a 1166 Connection determines that keep-alive packets are being sent, the 1167 applicaton should itself avoid generating additional keep alive 1168 messages. Note that when supported, the system will use the default 1169 period for generation of the keep alive-packets. (See also 1170 Section 8.1.4). 1172 6.2.11. Interface Instance or Type 1174 Name: interface 1176 Type: Collection of (Preference, Enumeration) 1178 Default: Empty (not setting a preference for any interface) 1180 This property allows the application to select any specific network 1181 interfaces or categories of interfaces it wants to "Require", 1182 "Prohibit", "Prefer", or "Avoid". Note that marking a specific 1183 interface as "Require" strictly limits path selection to that single 1184 interface, and often leads to less flexible and resilient connection 1185 establishment. 1187 In contrast to other Selection Properties, this property is a tuple 1188 of an (Enumerated) interface identifier and a preference, and can 1189 either be implemented directly as such, or for making one preference 1190 available for each interface and interface type available on the 1191 system. 1193 The set of valid interface types is implementation- and system- 1194 specific. For example, on a mobile device, there may be "Wi-Fi" and 1195 "Cellular" interface types available; whereas on a desktop computer, 1196 "Wi-Fi" and "Wired Ethernet" interface types might be available. An 1197 implementation should provide all types that are supported on the 1198 local system, to allow applications to be written generically. For 1199 example, if a single implementation is used on both mobile devices 1200 and desktop devices, it should define the "Cellular" interface type 1201 for both systems, since an application might wish to always prohibit 1202 cellular. 1204 The set of interface types is expected to change over time as new 1205 access technologies become available. The taxonomy of interface 1206 types on a given Transport Services system is implementation- 1207 specific. 1209 Interface types should not be treated as a proxy for properties of 1210 interfaces such as metered or unmetered network access. If an 1211 application needs to prohibit metered interfaces, this should be 1212 specified via Provisioning Domain attributes (see Section 6.2.12) or 1213 another specific property. 1215 6.2.12. Provisioning Domain Instance or Type 1217 Name: pvd 1219 Type: Collection of (Preference, Enumeration) 1221 Default: Empty (not setting a preference for any PvD) 1223 Similar to interface instances and types (see Section 6.2.11), this 1224 property allows the application to control path selection by 1225 selecting which specific Provisioning Domain (PvD) or categories of 1226 PVDs it wants to "Require", "Prohibit", "Prefer", or "Avoid". 1227 Provisioning Domains define consistent sets of network properties 1228 that may be more specific than network interfaces [RFC7556]. 1230 As with interface instances and types, this property is a tuple of an 1231 (Enumerated) PvD identifier and a preference, and can either be 1232 implemented directly as such, or for making one preference available 1233 for each interface and interface type available on the system. 1235 The identification of a specific PvD is implementation- and system- 1236 specific, because there is currently no portable standard format for 1237 a PvD identifier. For example, this identifier might be a string 1238 name or an integer. As with requiring specific interfaces, requiring 1239 a specific PvD strictly limits the path selection. 1241 Categories or types of PvDs are also defined to be implementation- 1242 and system-specific. These can be useful to identify a service that 1243 is provided by a PvD. For example, if an application wants to use a 1244 PvD that provides a Voice-Over-IP service on a Cellular network, it 1245 can use the relevant PvD type to require a PvD that provides this 1246 service, without needing to look up a particular instance. While 1247 this does restrict path selection, it is broader than requiring 1248 specific PvD instances or interface instances, and should be 1249 preferred over these options. 1251 6.2.13. Use Temporary Local Address 1253 Name: useTemporaryLocalAddress 1255 Type: Preference 1257 Default: Avoid for Listeners and Rendezvous Connections. Prefer for 1258 other Connections. 1260 This property allows the application to express a preference for the 1261 use of temporary local addresses, sometimes called "privacy" 1262 addresses [RFC4941]. Temporary addresses are generally used to 1263 prevent linking connections over time when a stable address, 1264 sometimes called "permanent" address, is not needed. There are some 1265 caveats to note when specifying this property. First, if an 1266 application Requires the use of temporary addresses, the resulting 1267 Connection cannot use IPv4, because temporary addresses do not exist 1268 in IPv4. Second, temporary local addresses might involve trading off 1269 privacy for performance. For instance, temporary addresses can 1270 interfere with resumption mechanisms that some protocols rely on to 1271 reduce initial latency. 1273 6.2.14. Multipath Transport 1275 Name: multipath 1277 Type: Enumeration 1279 Default: Disabled for connections created through initiate and 1280 rendezvous, Passive for listeners 1282 This property specifies whether and how applications want to take 1283 advantage of transferring data across multiple paths between the same 1284 end hosts. Using multiple paths allows connections to migrate 1285 between interfaces or aggregate bandwidth as availability and 1286 performance properties change. Possible values are: 1288 Disabled: The connection will not use multiple paths once 1289 established, even if the chosen transport supports using multiple 1290 paths. 1292 Active: The connection will negotiate the use of multiple paths if 1293 the chosen transport supports this. 1295 Passive: The connection will support the use of multiple paths if 1296 the Remote Endpoint requests it. 1298 The policy for using multiple paths is specified using the separate 1299 "multipath-policy" property, see Section 8.1.7 below. To enable the 1300 peer endpoint to initiate additional paths towards a local address 1301 other than the one initially used, it is necessary to set the 1302 Alternative Addresses property (see Section 6.2.15 below). 1304 Setting this property to "Active", can have privacy implications: It 1305 enables the transport to establish connectivity using alternate paths 1306 that might result in users being linkable across the multiple paths, 1307 even if the Advertisement of Alternative Addresses property (see 1308 Section 6.2.15 below) is set to false. 1310 Note that Multipath Transport has no corresponding Selection Property 1311 of type Preference. Enumeration values other than "Disabled" are 1312 interpreted as a preference for choosing protocols that can make use 1313 of multiple paths. The "Disabled" value implies a requirement not to 1314 use multiple paths in parallel but does not prevent choosing a 1315 protocol that is capable of using multiple paths, e.g., it does not 1316 prevent choosing TCP, but prevents sending the "MP_CAPABLE" option in 1317 the TCP handshake. 1319 6.2.15. Advertisement of Alternative Addresses 1321 Name: advertises-altaddr 1323 Type: Boolean 1325 Default: False 1327 This property specifies whether alternative addresses, e.g., of other 1328 interfaces, should be advertised to the peer endpoint by the protocol 1329 stack. Advertising these addresses enables the peer-endpoint to 1330 establish additional connectivity, e.g., for connection migration or 1331 using multiple paths. 1333 Note that this can have privacy implications because it might result 1334 in users being linkable across the multiple paths. Also, note that 1335 setting this to false does not prevent the local Transport Services 1336 system from _establishing_ connectivity using alternate paths (see 1337 Section 6.2.14 above); it only prevents _proactive advertisement_ of 1338 addresses. 1340 6.2.16. Direction of communication 1342 Name: direction 1344 Type: Enumeration 1346 Default: Bidirectional 1348 This property specifies whether an application wants to use the 1349 connection for sending and/or receiving data. Possible values are: 1351 Bidirectional: The connection must support sending and receiving 1352 data 1354 Unidirectional send: The connection must support sending data, and 1355 the application cannot use the connection to receive any data 1357 Unidirectional receive: The connection must support receiving data, 1358 and the application cannot use the connection to send any data 1360 Since unidirectional communication can be supported by transports 1361 offering bidirectional communication, specifying unidirectional 1362 communication may cause a transport stack that supports bidirectional 1363 communication to be selected. 1365 6.2.17. Notification of ICMP soft error message arrival 1367 Name: softErrorNotify 1369 Type: Preference 1371 Default: Ignore 1373 This property specifies whether an application considers it useful to 1374 be informed when an ICMP error message arrives that does not force 1375 termination of a connection. When set to true, received ICMP errors 1376 are available as SoftErrors, see Section 8.3.1. Note that even if a 1377 protocol supporting this property is selected, not all ICMP errors 1378 will necessarily be delivered, so applications cannot rely upon 1379 receiving them [RFC8085]. 1381 6.2.18. Initiating side is not the first to write 1383 Name: activeReadBeforeSend 1385 Type: Preference 1387 Default: Ignore 1389 The most common client-server communication pattern involves the 1390 client actively opening a connection, then sending data to the 1391 server. The server listens (passive open), reads, and then answers. 1392 This property specifies whether an application wants to diverge from 1393 this pattern - either by actively opening with Initiate(), 1394 immediately followed by reading, or passively opening with Listen(), 1395 immediately followed by writing. This property is ignored when 1396 establishing connections using Rendezvous(). Requiring this property 1397 limits the choice of mappings to underlying protocols, which can 1398 reduce efficiency. For example, it prevents the Transport Services 1399 system from mapping Connections to SCTP streams, where the first 1400 transmitted data takes the role of an active open signal 1401 [I-D.ietf-taps-impl]. 1403 6.3. Specifying Security Parameters and Callbacks 1405 Most security parameters, e.g., TLS ciphersuites, local identity and 1406 private key, etc., may be configured statically. Others are 1407 dynamically configured during connection establishment. Security 1408 parameters and callbacks are partitioned based on their place in the 1409 lifetime of connection establishment. Similar to Transport 1410 Properties, both parameters and callbacks are inherited during 1411 cloning (see Section 7.4). 1413 6.3.1. Specifying Security Parameters on a Pre-Connection 1415 Common security parameters such as TLS ciphersuites are known to 1416 implementations. Clients should use common safe defaults for these 1417 values whenever possible. However, as discussed in [RFC8922], many 1418 transport security protocols require specific security parameters and 1419 constraints from the client at the time of configuration and actively 1420 during a handshake. These configuration parameters need to be 1421 specified in the pre-connection phase and are created as follows: 1423 SecurityParameters := NewSecurityParameters() 1425 Security configuration parameters and sample usage follow: 1427 * Local identity and private keys: Used to perform private key 1428 operations and prove one's identity to the Remote Endpoint. 1429 (Note, if private keys are not available, e.g., since they are 1430 stored in hardware security modules (HSMs), handshake callbacks 1431 must be used. See below for details.) 1433 SecurityParameters.Set(identity, myIdentity) 1434 SecurityParameters.Set(key-pair, myPrivateKey, myPublicKey) 1436 * Supported algorithms: Used to restrict what parameters are used by 1437 underlying transport security protocols. When not specified, 1438 these algorithms should use known and safe defaults for the 1439 system. Parameters include: ciphersuites, supported groups, and 1440 signature algorithms. These parameters take a collection of 1441 supported algorithms as parameter. 1443 SecurityParameters.Set(supported-group, "secp256k1") 1444 SecurityParameters.Set(ciphersuite, "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256") 1445 SecurityParameters.Set(signature-algorithm, "ed25519") 1447 * Pre-Shared Key import: Used to install pre-shared keying material 1448 established out-of-band. Each pre-shared keying material is 1449 associated with some identity that typically identifies its use or 1450 has some protocol-specific meaning to the Remote Endpoint. 1452 SecurityParameters.Set(pre-shared-key, key, identity) 1454 * Session cache management: Used to tune session cache capacity, 1455 lifetime, and other policies. 1457 SecurityParameters.Set(max-cached-sessions, 16) 1458 SecurityParameters.Set(cached-session-lifetime-seconds, 3600) 1460 Connections that use Transport Services SHOULD use security in 1461 general. However, for compatibility with endpoints that do not 1462 support transport security protocols (such as a TCP endpoint that 1463 does not support TLS), applications can initialize their security 1464 parameters to indicate that security can be disabled, or can be 1465 opportunistic. If security is disabled, the Transport Services 1466 system will not attempt to add transport security automatically. If 1467 security is opportunistic, it will allow Connections without 1468 transport security, but will still attempt to use security if 1469 available. 1471 SecurityParameters := NewDisabledSecurityParameters() 1473 SecurityParameters := NewOpportunisticSecurityParameters() 1474 Representation of Security Parameters in implementations should 1475 parallel that chosen for Transport Property names as sugggested in 1476 Section 5. 1478 6.3.2. Connection Establishment Callbacks 1480 Security decisions, especially pertaining to trust, are not static. 1481 Once configured, parameters may also be supplied during connection 1482 establishment. These are best handled as client-provided callbacks. 1483 Callbacks block the progress of the connection establishment, which 1484 distinguishes them from other Events in the transport system. How 1485 callbacks and events are implemented is specific to each 1486 implementation. Security handshake callbacks that may be invoked 1487 during connection establishment include: 1489 * Trust verification callback: Invoked when a Remote Endpoint's 1490 trust must be validated before the handshake protocol can 1491 continue. 1493 TrustCallback := NewCallback({ 1494 // Handle trust, return the result 1495 }) 1496 SecurityParameters.SetTrustVerificationCallback(trustCallback) 1498 * Identity challenge callback: Invoked when a private key operation 1499 is required, e.g., when local authentication is requested by a 1500 Remote Endpoint. 1502 ChallengeCallback := NewCallback({ 1503 // Handle challenge 1504 }) 1505 SecurityParameters.SetIdentityChallengeCallback(challengeCallback) 1507 7. Establishing Connections 1509 Before a Connection can be used for data transfer, it needs to be 1510 established. Establishment ends the pre-establishment phase; all 1511 transport properties and cryptographic parameter specification must 1512 be complete before establishment, as these will be used to select 1513 candidate Paths and Protocol Stacks for the Connection. 1514 Establishment may be active, using the Initiate() Action; passive, 1515 using the Listen() Action; or simultaneous for peer-to-peer, using 1516 the Rendezvous() Action. These Actions are described in the 1517 subsections below. 1519 7.1. Active Open: Initiate 1521 Active open is the Action of establishing a Connection to a Remote 1522 Endpoint presumed to be listening for incoming Connection requests. 1523 Active open is used by clients in client-server interactions. Active 1524 open is supported by this interface through the Initiate Action: 1526 Connection := Preconnection.Initiate(timeout?) 1528 The timeout parameter specifies how long to wait before aborting 1529 Active open. Before calling Initiate, the caller must have populated 1530 a Preconnection Object with a Remote Endpoint specifier, optionally a 1531 Local Endpoint specifier (if not specified, the system will attempt 1532 to determine a suitable Local Endpoint), as well as all properties 1533 necessary for candidate selection. 1535 The Initiate() Action returns a Connection object. Once Initiate() 1536 has been called, any changes to the Preconnection MUST NOT have any 1537 effect on the Connection. However, the Preconnection can be reused, 1538 e.g., to Initiate another Connection. 1540 Once Initiate is called, the candidate Protocol Stack(s) may cause 1541 one or more candidate transport-layer connections to be created to 1542 the specified Remote Endpoint. The caller may immediately begin 1543 sending Messages on the Connection (see Section 9.2) after calling 1544 Initiate(); note that any data marked "Safely Replayable" that is 1545 sent while the Connection is being established may be sent multiple 1546 times or on multiple candidates. 1548 The following Events may be sent by the Connection after Initiate() 1549 is called: 1551 Connection -> Ready<> 1553 The Ready Event occurs after Initiate has established a transport- 1554 layer connection on at least one usable candidate Protocol Stack over 1555 at least one candidate Path. No Receive Events (see Section 9.3) 1556 will occur before the Ready Event for Connections established using 1557 Initiate. 1559 Connection -> EstablishmentError 1561 An EstablishmentError occurs either when the set of transport 1562 properties and security parameters cannot be fulfilled on a 1563 Connection for initiation (e.g., the set of available Paths and/or 1564 Protocol Stacks meeting the constraints is empty) or reconciled with 1565 the Local and/or Remote Endpoints; when the remote specifier cannot 1566 be resolved; or when no transport-layer connection can be established 1567 to the Remote Endpoint (e.g., because the Remote Endpoint is not 1568 accepting connections, the application is prohibited from opening a 1569 Connection by the operating system, or the establishment attempt has 1570 timed out for any other reason). 1572 Connection establishment and transmission of the first message can be 1573 combined in a single action Section 9.2.5. 1575 7.2. Passive Open: Listen 1577 Passive open is the Action of waiting for Connections from Remote 1578 Endpoints, commonly used by servers in client-server interactions. 1579 Passive open is supported by this interface through the Listen Action 1580 and returns a Listener object: 1582 Listener := Preconnection.Listen() 1584 Before calling Listen, the caller must have initialized the 1585 Preconnection during the pre-establishment phase with a Local 1586 Endpoint specifier, as well as all properties necessary for Protocol 1587 Stack selection. A Remote Endpoint may optionally be specified, to 1588 constrain what Connections are accepted. 1590 The Listen() Action returns a Listener object. Once Listen() has 1591 been called, any changes to the Preconnection MUST NOT have any 1592 effect on the Listener. The Preconnection can be disposed of or 1593 reused, e.g., to create another Listener. 1595 Listener.Stop() 1597 Listening continues until the global context shuts down, or until the 1598 Stop action is performed on the Listener object. 1600 Listener -> ConnectionReceived 1602 The ConnectionReceived Event occurs when a Remote Endpoint has 1603 established a transport-layer connection to this Listener (for 1604 Connection-oriented transport protocols), or when the first Message 1605 has been received from the Remote Endpoint (for Connectionless 1606 protocols), causing a new Connection to be created. The resulting 1607 Connection is contained within the ConnectionReceived Event, and is 1608 ready to use as soon as it is passed to the application via the 1609 event. 1611 Listener.SetNewConnectionLimit(value) 1612 If the caller wants to rate-limit the number of inbound Connections 1613 that will be delivered, it can set a cap using 1614 SetNewConnectionLimit(). This mechanism allows a server to protect 1615 itself from being drained of resources. Each time a new Connection 1616 is delivered by the ConnectionReceived Event, the value is 1617 automatically decremented. Once the value reaches zero, no further 1618 Connections will be delivered until the caller sets the limit to a 1619 higher value. By default, this value is Infinite. The caller is 1620 also able to reset the value to Infinite at any point. 1622 Listener -> EstablishmentError 1624 An EstablishmentError occurs either when the Properties and Security 1625 Parameters of the Preconnection cannot be fulfilled for listening or 1626 cannot be reconciled with the Local Endpoint (and/or Remote Endpoint, 1627 if specified), when the Local Endpoint (or Remote Endpoint, if 1628 specified) cannot be resolved, or when the application is prohibited 1629 from listening by policy. 1631 Listener -> Stopped<> 1633 A Stopped Event occurs after the Listener has stopped listening. 1635 7.3. Peer-to-Peer Establishment: Rendezvous 1637 Simultaneous peer-to-peer Connection establishment is supported by 1638 the Rendezvous() Action: 1640 Preconnection.Rendezvous() 1642 A Preconnection Object used in a Rendezvous() MUST have both the 1643 Local Endpoint candidates and the Remote Endpoint candidates 1644 specified, along with the transport properties and security 1645 parameters needed for Protocol Stack selection, before the 1646 Rendezvous() Action is initiated. 1648 The Rendezvous() Action listens on the Local Endpoint candidates for 1649 an incoming Connection from the Remote Endpoint candidates, while 1650 also simultaneously trying to establish a Connection from the Local 1651 Endpoint candidates to the Remote Endpoint candidates. 1653 If there are multiple Local Endpoints or Remote Endpoints configured, 1654 then initiating a Rendezvous() action will systematically probe the 1655 reachability of those endpoint candidates following an approach such 1656 as that used in Interactive Connectivity Establishment (ICE) 1657 [RFC5245]. 1659 If the endpoints are suspected to be behind a NAT, Rendezvous() can 1660 be initiated using Local Endpoints that support a method of 1661 discovering NAT bindings such as Session Traversal Utilities for NAT 1662 (STUN) [RFC8489] or Traversal Using Relays around NAT (TURN) 1663 [RFC5766]. In this case, the Local Endpoint will resolve to a 1664 mixture of local and server reflexive addresses. The Resolve() 1665 action on the Preconnection can be used to discover these bindings: 1667 []LocalEndpoint, []RemoteEndpoint := Preconnection.Resolve() 1669 The Resolve() call returns lists of Local Endpoints and Remote 1670 Endpoints, that represent the concrete addresses, local and server 1671 reflexive, on which a Rendezvous() for the Preconnection will listen 1672 for incoming Connections, and to which it will attempt to establish 1673 connections. 1675 An application that uses Rendezvous() to establish a peer-to-peer 1676 connection in the presence of NATs will configure the Preconnection 1677 object with at least one a Local Endpoint that supports NAT binding 1678 discovery. It will then Resolve() the Preconnection, and pass the 1679 resulting list of Local Endpoint candidates to the peer via a 1680 signalling protocol, for example as part of an ICE [RFC5245] exchange 1681 within SIP [RFC3261] or WebRTC [RFC7478]. The peer will then, via 1682 the same signalling channel, return the Remote Endpoint candidates. 1683 The set of Remote Endpoint candidates are then configured onto the 1684 Preconnection: 1686 Preconnection.AddRemote([]RemoteEndpoint) 1688 The Rendezvous() Action can be initiated once both the Local Endpoint 1689 candidates and the Remote Endpoint candidates retrieved from the peer 1690 via the signalling channel have been added to the Preconnection. 1692 If successful, the Rendezvous() Action returns a Connection object 1693 via a RendezvousDone<> Event: 1695 Preconnection -> RendezvousDone 1697 The RendezvousDone<> Event occurs when a Connection is established 1698 with the Remote Endpoint. For Connection-oriented transports, this 1699 occurs when the transport-layer connection is established; for 1700 Connectionless transports, it occurs when the first Message is 1701 received from the Remote Endpoint. The resulting Connection is 1702 contained within the RendezvousDone<> Event, and is ready to use as 1703 soon as it is passed to the application via the Event. Changes made 1704 to a Preconnection after Rendezvous() has been called do not have any 1705 effect on existing Connections. 1707 An EstablishmentError occurs either when the Properties and Security 1708 Parameters of the Preconnection cannot be fulfilled for rendezvous or 1709 cannot be reconciled with the Local and/or Remote Endpoints, when the 1710 Local Endpoint or Remote Endpoint cannot be resolved, when no 1711 transport-layer connection can be established to the Remote Endpoint, 1712 or when the application is prohibited from rendezvous by policy: 1714 Preconnection -> EstablishmentError 1716 7.4. Connection Groups 1718 Connection Groups can be created using the Clone Action: 1720 Connection := Connection.Clone(framer?) 1722 Calling Clone on a Connection yields a Connection Group containing 1723 two Connections: the parent Connection on which Clone was called, and 1724 a resulting cloned Connection. The new Connection is actively 1725 openend, and it will send a Ready Event or an EstablishmentError 1726 Event. Calling Clone on any of these Connections adds another 1727 Connection to the Connection Group. Connections in a Connection 1728 Group share all Connection Properties except "Connection Priority" 1729 (see Section 8.1.2), and these Connection Properties are entangled: 1730 Changing one of the Connection Properties on one Connection in the 1731 Connection Group automatically changes the Connection Property for 1732 all others. For example, changing "Timeout for aborting Connection" 1733 (see Section 8.1.3) on one Connection in a Connection Group will 1734 automatically make the same change to this Connection Property for 1735 all other Connections in the Connection Group. Like all other 1736 Properties, "Connection Priority" is copied to the new Connection 1737 when calling Clone(), but in this case, a later change to the 1738 "Connection Priority" on one Connection does not change it on the 1739 other Connections in the same Connection Group. 1741 Message Properties are also not entangled. For example, changing 1742 "Lifetime" (see Section 9.1.3.1) of a Message will only affect a 1743 single Message on a single Connection. 1745 A new Connection created by Clone can have a Message Framer assigned 1746 via the optional "framer" parameter of the Clone Action. If this 1747 parameter is not supplied, the stack of Message Framers associated 1748 with a Connection is copied to the cloned Connection when calling 1749 Clone. Then, a cloned Connection has the same stack of Message 1750 Framers as the Connection from which they are Cloned, but these 1751 Framers may internally maintain per-Connection state. 1753 It is also possible to check which Connections belong to the same 1754 Connection Group. Calling GroupedConnections() on a specific 1755 Connection returns a set of all Connections in the same group. 1757 []Connection := Connection.GroupedConnections() 1759 Connections will belong to the same group if the application 1760 previously called Clone. Passive Connections can also be added to 1761 the same group - e.g., when a Listener receives a new Connection that 1762 is just a new stream of an already active multi-streaming protocol 1763 instance. 1765 If the underlying protocol supports multi-streaming, it is natural to 1766 use this functionality to implement Clone. In that case, Connections 1767 in a Connection Group are multiplexed together, giving them similar 1768 treatment not only inside endpoints, but also across the end-to-end 1769 Internet path. 1771 Note that calling Clone() can result in on-the-wire signaling, e.g., 1772 to open a new transport connection, depending on the underlying 1773 Protocol Stack. When Clone() leads to the opening of multiple such 1774 connections, the Transport Services system will ensure consistency of 1775 Connection Properties by uniformly applying them to all underlying 1776 connections in a group. Even in such a case, there are possibilities 1777 for a Transport Services system to implement prioritization within a 1778 Connection Group [TCP-COUPLING] [RFC8699]. 1780 Attempts to clone a Connection can result in a CloneError: 1782 Connection -> CloneError 1784 The "Connection Priority" Connection Property operates on Connections 1785 in a Connection Group using the same approach as in Section 9.1.3.2: 1786 when allocating available network capacity among Connections in a 1787 Connection Group, sends on Connections with lower Priority values 1788 will be prioritized over sends on Connections with higher Priority 1789 values. Capacity will be shared among these Connections according to 1790 the Connection Group Transmission Scheduler property (Section 8.1.5). 1791 See Section 9.2.6 for more. 1793 8. Managing Connections 1795 During pre-establishment and after establishment, connections can be 1796 configured and queried using Connection Properties, and asynchronous 1797 information may be available about the state of the connection via 1798 Soft Errors. 1800 Connection Properties represent the configuration and state of the 1801 selected Protocol Stack(s) backing a Connection. These Connection 1802 Properties may be Generic, applying regardless of transport protocol, 1803 or Specific, applicable to a single implementation of a single 1804 transport protocol stack. Generic Connection Properties are defined 1805 in Section 8.1 below. 1807 Protocol Specific Properties are defined in a transport- and 1808 implementation-specific way, and MUST NOT apply across different 1809 protocols. Too much reliance by an application on Protocol Specific 1810 Properties can significantly reduce the flexibility of a transport 1811 services implementation. 1813 The application can set and query Connection Properties on a per- 1814 Connection basis. Connection Properties that are not read-only can 1815 be set during pre-establishment (see Section 6.2), as well as on 1816 connections directly using the SetProperty action: 1818 Connection.SetProperty(property, value) 1820 Note that changing one of the Connection Properties on one Connection 1821 in a Connection Group will also change it for all other Connections 1822 of that group; see further Section 7.4. 1824 At any point, the application can query Connection Properties. 1826 ConnectionProperties := Connection.GetProperties() 1827 value := ConnectionProperties.Get(property) 1828 if ConnectionProperties.Has(boolean_or_preference_property) then ... 1830 Depending on the status of the connection, the queried Connection 1831 Properties will include different information: 1833 * The connection state, which can be one of the following: 1834 Establishing, Established, Closing, or Closed. 1836 * Whether the connection can be used to send data. A connection can 1837 not be used for sending if the connection was created with the 1838 Selection Property "Direction of Communication" set to 1839 "unidirectional receive" or if a Message marked as "Final" was 1840 sent over this connection. See also Section 9.1.3.5. 1842 * Whether the connection can be used to receive data. A connection 1843 cannot be used for reading if the connection was created with the 1844 Selection Property "Direction of Communication" set to 1845 "unidirectional send" or if a Message marked as "Final" was 1846 received. See Section 9.3.3.3. The latter is only supported by 1847 certain transport protocols, e.g., by TCP as half-closed 1848 connection. 1850 * For Connections that are Established, Closing, or Closed: 1851 Connection Properties (Section 8.1) of the actual protocols that 1852 were selected and instantiated, and Selection Properties that the 1853 application specified on the Preconnection. Selection Properties 1854 of type "Preference" will be exposed as boolean values indicating 1855 whether or not the property applies to the selected transport. 1856 Note that the instantiated protocol stack might not match all 1857 Protocol Selection Properties that the application specified on 1858 the Preconnection. 1860 * For Connections that are Established, additional properties of the 1861 path(s) in use. These properties can be derived from the local 1862 provisioning domain [RFC7556], measurements by the Protocol Stack, 1863 or other sources. 1865 8.1. Generic Connection Properties 1867 Generic Connection Properties are defined independent of the chosen 1868 protocol stack and therefore available on all Connections. 1870 Many Connection Properties have a corresponding Selection Property 1871 that enables applications to express their preference for protocols 1872 providing a supporting transport feature. 1874 8.1.1. Required Minimum Corruption Protection Coverage for Receiving 1876 Name: recvChecksumLen 1878 Type: Integer (non-negative with special value "Full Coverage") 1880 Default: Full Coverage 1882 This property specifies the minimum number of bytes in a received 1883 message that need to be covered by a checksum. A special value of 0 1884 means that a received packet does not need to have a non-zero 1885 checksum field. A receiving endpoint will not forward messages that 1886 have less coverage to the application. The application is 1887 responsible for handling any corruption within the non-protected part 1888 of the message [RFC8085]. 1890 8.1.2. Connection Priority 1892 Name: connPrio 1894 Type: Integer 1896 Default: 100 1898 This Property is a non-negative integer representing the relative 1899 inverse priority (i.e., a lower value reflects a higher priority) of 1900 this Connection relative to other Connections in the same Connection 1901 Group. It has no effect on Connections not part of a Connection 1902 Group. As noted in Section 7.4, this property is not entangled when 1903 Connections are cloned, i.e., changing the Priority on one Connection 1904 in a Connection Group does not change it on the other Connections in 1905 the same Connection Group. No guarantees of a specific behavior 1906 regarding Connection Priority are given; a Transport Services system 1907 may ignore this property. See Section 9.2.6 for more details. 1909 8.1.3. Timeout for Aborting Connection 1911 Name: connTimeout 1913 Type: Numeric, with special value "Disabled" 1915 Default: Disabled 1917 This property specifies how long to wait before deciding that an 1918 active Connection has failed when trying to reliably deliver data to 1919 the Remote Endpoint. Adjusting this Property will only take effect 1920 when the underlying stack supports reliability. The special value 1921 "Disabled" means that no timeout is scheduled. 1923 8.1.4. Timeout for keep alive packets 1925 Name: keepAliveTimeout 1927 Type: Numeric, with special value "Disabled" 1929 Default: Implementation-defined 1931 A Transport Services system can request a protocol that supports 1932 sending keep alive packets Section 6.2.10. This property specifies 1933 the maximum length of time an idle connection (one for which no 1934 transport packets have been sent) should wait before the Local 1935 Endpoint sends a keep-alive packet to the Remote Endpoint. Adjusting 1936 this Property will only take effect when the underlying stack 1937 supports sending keep-alive packets. Guidance on setting this value 1938 for datagram transports is provided in [RFC8085]. A value greater 1939 than the connection timeout (Section 8.1.3), or the special value 1940 "Disabled", will disable the sending of keep-alive packets. 1942 8.1.5. Connection Group Transmission Scheduler 1944 Name: connScheduler 1946 Type: Enumeration 1948 Default: Weighted Fair Queueing (see Section 3.6 in [RFC8260]) 1950 This property specifies which scheduler should be used among 1951 Connections within a Connection Group, see Section 7.4. The set of 1952 schedulers can be taken from [RFC8260]. 1954 8.1.6. Capacity Profile 1956 Name: connCapacityProfile 1958 This property specifies the desired network treatment for traffic 1959 sent by the application and the tradeoffs the application is prepared 1960 to make in path and protocol selection to receive that desired 1961 treatment. When the capacity profile is set to a value other than 1962 Default, the Transport Services system SHOULD select paths and 1963 configure protocols to optimize the tradeoff between delay, delay 1964 variation, and efficient use of the available capacity based on the 1965 capacity profile specified. How this is realized is implementation- 1966 specific. The Capacity Profile MAY also be used to set markings on 1967 the wire for Protocol Stacks supporting this. Recommendations for 1968 use with DSCP are provided below for each profile; note that when a 1969 Connection is multiplexed, the guidelines in Section 6 of [RFC7657] 1970 apply. 1972 The following values are valid for the Capacity Profile: 1974 Default: The application provides no information about its expected 1975 capacity profile. Transport Services system implementations that 1976 map the requested capacity profile onto per-connection DSCP 1977 signaling SHOULD assign the DSCP Default Forwarding [RFC2474] Per 1978 Hop Behaviour (PHB). 1980 Scavenger: The application is not interactive. It expects to send 1981 and/or receive data without any urgency. This can, for example, 1982 be used to select protocol stacks with scavenger transmission 1983 control and/or to assign the traffic to a lower-effort service. 1984 Transport Services system implementations that map the requested 1985 capacity profile onto per-connection DSCP signaling SHOULD assign 1986 the DSCP Less than Best Effort [RFC8622] PHB. 1988 Low Latency/Interactive: The application is interactive, and prefers 1989 loss to latency. Response time should be optimized at the expense 1990 of delay variation and efficient use of the available capacity 1991 when sending on this connection. This can be used by the system 1992 to disable the coalescing of multiple small Messages into larger 1993 packets (Nagle's algorithm); to prefer immediate acknowledgment 1994 from the peer endpoint when supported by the underlying transport; 1995 and so on. Transport Services system implementations that map the 1996 requested capacity profile onto per-connection DSCP signaling 1997 without multiplexing SHOULD assign a DSCP Assured Forwarding 1998 (AF41,AF42,AF43,AF44) [RFC2597] PHB. Inelastic traffic that is 1999 expected to conform to the configured network service rate could 2000 be mapped to the DSCP Expedited Forwarding [RFC3246] or [RFC5865] 2001 PHBs. 2003 Low Latency/Non-Interactive: The application prefers loss to 2004 latency, but is not interactive. Response time should be 2005 optimized at the expense of delay variation and efficient use of 2006 the available capacity when sending on this connection. Transport 2007 system implementations that map the requested capacity profile 2008 onto per-connection DSCP signaling without multiplexing SHOULD 2009 assign a DSCP Assured Forwarding (AF21,AF22,AF23,AF24) [RFC2597] 2010 PHB. 2012 Constant-Rate Streaming: The application expects to send/receive 2013 data at a constant rate after Connection establishment. Delay and 2014 delay variation should be minimized at the expense of efficient 2015 use of the available capacity. This implies that the Connection 2016 might fail if the Path is unable to maintain the desired rate. A 2017 transport can interpret this capacity profile as preferring a 2018 circuit breaker [RFC8084] to a rate-adaptive congestion 2019 controller. Transport system implementations that map the 2020 requested capacity profile onto per-connection DSCP signaling 2021 without multiplexing SHOULD assign a DSCP Assured Forwarding 2022 (AF31,AF32,AF33,AF34) [RFC2597] PHB. 2024 Capacity-Seeking: The application expects to send/receive data at 2025 the maximum rate allowed by its congestion controller over a 2026 relatively long period of time. Transport Services system 2027 implementations that map the requested capacity profile onto per- 2028 connection DSCP signaling without multiplexing SHOULD assign a 2029 DSCP Assured Forwarding (AF11,AF12,AF13,AF14) [RFC2597] PHB per 2030 Section 4.8 of [RFC4594]. 2032 The Capacity Profile for a selected protocol stack may be modified on 2033 a per-Message basis using the Transmission Profile Message Property; 2034 see Section 9.1.3.8. 2036 8.1.7. Policy for using Multipath Transports 2038 Name: multipath-policy 2040 Type: Enumeration 2042 Default: Handover 2044 This property specifies the local policy for transferring data across 2045 multiple paths between the same end hosts if Multipath Transport is 2046 not set to Disabled (see Section 6.2.14). Possible values are: 2048 Handover: The connection ought only to attempt to migrate between 2049 different paths when the original path is lost or becomes 2050 unusable. The thresholds used to declare a path unusable are 2051 implementation specific. 2053 Interactive: The connection ought only to attempt to minimize the 2054 latency for interactive traffic patterns by transmitting data 2055 across multiple paths when this is beneficial. The goal of 2056 minimizing the latency will be balanced against the cost of each 2057 of these paths. Depending on the cost of the lower-latency path, 2058 the scheduling might choose to use a higher-latency path. Traffic 2059 can be scheduled such that data may be transmitted on multiple 2060 paths in parallel to achieve a lower latency. The specific 2061 scheduling algorithm is implementation-specific. 2063 Aggregate: The connection ought to attempt to use multiple paths in 2064 parallel to maximize available capacity and possibly overcome the 2065 capacity limitations of the individual paths. The actual strategy 2066 is implementation specific. 2068 Note that this is a local choice - the Remote Endpoint can choose a 2069 different policy. 2071 8.1.8. Bounds on Send or Receive Rate 2073 Name: minSendRate / minRecvRate / maxSendRate / maxRecvRate 2075 Type: Numeric (with special value "Unlimited") / Numeric (with 2076 special value "Unlimited") / Numeric (with special value 2077 "Unlimited") / Numeric (with special value "Unlimited") 2079 Default: Unlimited / Unlimited / Unlimited / Unlimited 2081 This property specifies an upper-bound rate that a transfer is not 2082 expected to exceed (even if flow control and congestion control allow 2083 higher rates), and/or a lower-bound rate below which the application 2084 does not deem it will be useful. These are specified in bits per 2085 second. The special value "Unlimited" indicates that no bound is 2086 specified. 2088 8.1.9. Group Connection Limit 2090 Name: groupConnLimit 2092 Type: Numeric (with special value "Unlimited") 2094 Default: Unlimited 2096 This property controls the number of Connections that can be accepted 2097 from a peer as new members of the Connection's group. Similar to 2098 SetNewConnectionLimit(), this limits the number of ConnectionReceived 2099 Events that will occur, but constrained to the group of the 2100 Connection associated with this property. For a multi-streaming 2101 transport, this limits the number of allowed streams. 2103 8.1.10. Isolate Session 2105 Name: isolateSession 2107 Type: Boolean 2109 Default: false 2111 When set to true, this property will initiate new Connections using 2112 as little cached information (such as session tickets or cookies) as 2113 possible from previous connections that are not in the same 2114 Connection Group. Any state generated by this Connection will only 2115 be shared with Connections in the same Connection Group. Cloned 2116 Connections will use saved state from within the Connection Group. 2117 This is used for separating Connection Contexts as specified in 2118 [I-D.ietf-taps-arch]. 2120 Note that this does not guarantee no leakage of information, as 2121 implementations may not be able to fully isolate all caches (e.g. 2122 RTT estimates). Note that this property may degrade connection 2123 performance. 2125 8.1.11. Read-only Connection Properties 2127 The following generic Connection Properties are read-only, i.e. they 2128 cannot be changed by an application. 2130 8.1.11.1. Maximum Message Size Concurrent with Connection Establishment 2132 Name: zeroRttMsgMaxLen 2134 Type: Integer 2136 This property represents the maximum Message size that can be sent 2137 before or during Connection establishment, see also Section 9.1.3.4. 2138 It is given in Bytes. 2140 8.1.11.2. Maximum Message Size Before Fragmentation or Segmentation 2142 Name: singularTransmissionMsgMaxLen 2144 Type: Integer 2146 This property, if applicable, represents the maximum Message size 2147 that can be sent without incurring network-layer fragmentation at the 2148 sender. It exposes a value to the application based on the Maximum 2149 Packet Size (MPS) as described in Datagram PLPMTUD [RFC8899]. This 2150 can allow a sending stack to avoid unwanted fragmentation at the 2151 network-layer or segmentation by the transport layer. 2153 8.1.11.3. Maximum Message Size on Send 2155 Name: sendMsgMaxLen 2157 Type: Integer 2159 This property represents the maximum Message size that an application 2160 can send. 2162 8.1.11.4. Maximum Message Size on Receive 2164 Name: recvMsgMaxLen 2166 Type: Integer 2167 This numeric property represents the maximum Message size that an 2168 application can receive. 2170 8.2. TCP-specific Properties: User Timeout Option (UTO) 2172 These properties specify configurations for the User Timeout Option 2173 (UTO), in the case that TCP becomes the chosen transport protocol. 2174 Implementation is optional and useful only if TCP is implemented in 2175 the Transport Services system. 2177 These TCP-specific properties are included here because the feature 2178 "Suggest timeout to the peer" is part of the minimal set of transport 2179 services [RFC8923], where this feature was categorized as 2180 "functional". This means that when an implementation offers this 2181 feature, it has to expose an interface to it to the application. 2182 Otherwise, the implementation might violate assumptions by the 2183 application, which could cause the application to fail. 2185 All of the below properties are optional (e.g., it is possible to 2186 specify "User Timeout Enabled" as true, but not specify an Advertised 2187 User Timeout value; in this case, the TCP default will be used). 2188 These properties reflect the API extension specified in Section 3 of 2189 [RFC5482]. 2191 8.2.1. Advertised User Timeout 2193 Name: tcp.userTimeoutValue 2195 Type: Integer 2197 Default: the TCP default 2199 This time value is advertised via the TCP User Timeout Option (UTO) 2200 [RFC5482] at the Remote Endpoint to adapt its own "Timeout for 2201 aborting Connection" (see Section 8.1.3) value. 2203 8.2.2. User Timeout Enabled 2205 Name: tcp.userTimeout 2207 Type: Boolean 2209 Default: false 2211 This property controls whether the UTO option is enabled for a 2212 connection. This applies to both sending and receiving. 2214 8.2.3. Timeout Changeable 2216 Name: tcp.userTimeoutRecv 2218 Type: Boolean 2220 Default: true 2222 This property controls whether the "Timeout for aborting Connection" 2223 (see Section 8.1.3) may be changed based on a UTO option received 2224 from the remote peer. This boolean becomes false when "Timeout for 2225 aborting Connection" (see Section 8.1.3) is used. 2227 8.3. Connection Lifecycle Events 2229 During the lifetime of a connection there are events that can occur 2230 when configured. 2232 8.3.1. Soft Errors 2234 Asynchronous introspection is also possible, via the SoftError Event. 2235 This event informs the application about the receipt and contents of 2236 an ICMP error message related to the Connection. This will only 2237 happen if the underlying protocol stack supports access to soft 2238 errors; however, even if the underlying stack supports it, there is 2239 no guarantee that a soft error will be signaled. 2241 Connection -> SoftError<> 2243 8.3.2. Path change 2245 This event notifies the application when at least one of the paths 2246 underlying a Connection has changed. Changes occur on a single path 2247 when the PMTU changes as well as when multiple paths are used and 2248 paths are added or removed, or a handover has been performed. 2250 Connection -> PathChange<> 2252 9. Data Transfer 2254 Data is sent and received as Messages, which allows the application 2255 to communicate the boundaries of the data being transferred. 2257 9.1. Messages and Framers 2259 Each Message has an optional Message Context, which allows to add 2260 Message Properties, identify Send Events related to a specific 2261 Message or to inspect meta-data related to the Message sent. Framers 2262 can be used to extend or modify the message data with additional 2263 information that can be processed at the receiver to detect message 2264 boundaries. 2266 9.1.1. Message Contexts 2268 Using the MessageContext object, the application can set and retrieve 2269 meta-data of the message, including Message Properties (see 2270 Section 9.1.3) and framing meta-data (see Section 9.1.2.2). 2271 Therefore, a MessageContext object can be passed to the Send action 2272 and is returned by each Send and Receive related event. 2274 Message Properties can be set and queried using the Message Context: 2276 MessageContext.add(scope?, parameter, value) 2277 PropertyValue := MessageContext.get(scope?, property) 2279 To get or set Message Properties, the optional scope parameter is 2280 left empty. To get or set meta-data for a Framer, the application 2281 has to pass a reference to this Framer as the scope parameter. 2283 For MessageContexts returned by send Events (see Section 9.2.2) and 2284 receive Events (see Section 9.3.2), the application can query 2285 information about the Local and Remote Endpoint: 2287 RemoteEndpoint := MessageContext.GetRemoteEndpoint() 2288 LocalEndpoint := MessageContext.GetLocalEndpoint() 2290 9.1.2. Message Framers 2292 Although most applications communicate over a network using well- 2293 formed Messages, the boundaries and metadata of the Messages are 2294 often not directly communicated by the transport protocol itself. 2295 For example, HTTP applications send and receive HTTP messages over a 2296 byte-stream transport, requiring that the boundaries of HTTP messages 2297 be parsed from the stream of bytes. 2299 Message Framers allow extending a Connection's Protocol Stack to 2300 define how to encapsulate or encode outbound Messages, and how to 2301 decapsulate or decode inbound data into Messages. Message Framers 2302 allow message boundaries to be preserved when using a Connection 2303 object, even when using byte-stream transports. This is designed 2304 based on the fact that many of the current application protocols 2305 evolved over TCP, which does not provide message boundary 2306 preservation, and since many of these protocols require message 2307 boundaries to function, each application layer protocol has defined 2308 its own framing. 2310 To use a Message Framer, the application adds it to its Preconnection 2311 object. Then, the Message Framer can intercept all calls to Send() 2312 or Receive() on a Connection to add Message semantics, in addition to 2313 interacting with the setup and teardown of the Connection. A Framer 2314 can start sending data before the application sends data if the 2315 framing protocol requires a prefix or handshake (see [RFC8229] for an 2316 example of such a framing protocol). 2318 Initiate() Send() Receive() Close() 2319 | | ^ | 2320 | | | | 2321 +----v----------v---------+----------v-----+ 2322 | Connection | 2323 +----+----------+---------^----------+-----+ 2324 | | | | 2325 | +-----------------+ | 2326 | | Messages | | 2327 | +-----------------+ | 2328 | | | | 2329 +----v----------v---------+----------v-----+ 2330 | Framer(s) | 2331 +----+----------+---------^----------+-----+ 2332 | | | | 2333 | +-----------------+ | 2334 | | Byte-stream | | 2335 | +-----------------+ | 2336 | | | | 2337 +----v----------v---------+----------v-----+ 2338 | Transport Protocol Stack | 2339 +------------------------------------------+ 2341 Figure 1: Protocol Stack showing a Message Framer 2343 Note that while Message Framers add the most value when placed above 2344 a protocol that otherwise does not preserve message boundaries, they 2345 can also be used with datagram- or message-based protocols. In these 2346 cases, they add an additional transformation to further encode or 2347 encapsulate, and can potentially support packing multiple 2348 application-layer Messages into individual transport datagrams. 2350 The API to implement a Message Framer can vary depending on the 2351 implementation; guidance on implementing Message Framers can be found 2352 in [I-D.ietf-taps-impl]. 2354 9.1.2.1. Adding Message Framers to Pre-Connections 2356 The Message Framer object can be added to one or more Preconnections 2357 to run on top of transport protocols. Multiple Framers may be added 2358 to a Preconnection; in this case, the Framers operate as a framing 2359 stack, i.e. the last one added runs first when framing outbound 2360 messages, and last when parsing inbound data. 2362 The following example adds a basic HTTP Message Framer to a 2363 Preconnection: 2365 framer := NewHTTPMessageFramer() 2366 Preconnection.AddFramer(framer) 2368 Since Message Framers pass from Preconnection to Listener or 2369 Connection, addition of Framers must happen before any operation that 2370 may result in the creation of a Connection. 2372 9.1.2.2. Framing Meta-Data 2374 When sending Messages, applications can add Framer-specific key/value 2375 pairs to a MessageContext (Section 9.1.1). This mechanism can be 2376 used, for example, to set the type of a Message for a TLV format. 2377 The namespace of values is custom for each unique Message Framer. 2379 messageContext := NewMessageContext() 2380 messageContext.add(framer, key, value) 2381 Connection.Send(messageData, messageContext) 2383 When an application receives a MessageContext in a Receive event, it 2384 can also look to see if a value was set by a specific Message Framer. 2386 messageContext.get(framer, key) -> value 2388 For example, if an HTTP Message Framer is used, the values could 2389 correspond to HTTP headers: 2391 httpFramer := NewHTTPMessageFramer() 2392 ... 2393 messageContext := NewMessageContext() 2394 messageContext.add(httpFramer, "accept", "text/html") 2396 9.1.3. Message Properties 2398 Applications needing to annotate the Messages they send with extra 2399 information (for example, to control how data is scheduled and 2400 processed by the transport protocols supporting the Connection) can 2401 include this information in the Message Context passed to the Send 2402 Action. For other uses of the message context, see Section 9.1.1. 2404 Message Properties are per-Message, not per-Send if partial Messages 2405 are sent (Section 9.2.3). All data blocks associated with a single 2406 Message share properties specified in the Message Contexts. For 2407 example, it would not make sense to have the beginning of a Message 2408 expire, but allow the end of a Message to still be sent. 2410 A MessageContext object contains metadata for the Messages to be sent 2411 or received. 2413 messageData := "hello" 2414 messageContext := NewMessageContext() 2415 messageContext.add(parameter, value) 2416 Connection.Send(messageData, messageContext) 2418 The simpler form of Send, which does not take any messageContext, is 2419 equivalent to passing a default MessageContext without adding any 2420 Message Properties. 2422 If an application wants to override Message Properties for a specific 2423 message, it can acquire an empty MessageContext Object and add all 2424 desired Message Properties to that Object. It can then reuse the 2425 same messageContext Object for sending multiple Messages with the 2426 same properties. 2428 Properties can be added to a MessageContext object only before the 2429 context is used for sending. Once a messageContext has been used 2430 with a Send call, it is invalid to modify any of its properties. 2432 The Message Properties could be inconsistent with the properties of 2433 the Protocol Stacks underlying the Connection on which a given 2434 Message is sent. For example, a Protocol Stack must be able to 2435 provide ordering if the msgOrdered property of a Message is enabled. 2436 Sending a Message with Message Properties inconsistent with the 2437 Selection Properties of the Connection yields an error. 2439 Connection Properties describe the default behavior for all Messages 2440 on a Connection. If a Message Property contradicts a Connection 2441 Property, and if this per-Message behavior can be supported, it 2442 overrides the Connection Property for the specific Message. For 2443 example, if "Reliable Data Transfer (Connection)" is set to "Require" 2444 and a protocol with configurable per-Message reliability is used, 2445 setting "Reliable Data Transfer (Message)" to "false" for a 2446 particular Message will allow this Message to be sent without any 2447 reliability guarantees. Changing the Reliable Data Transfer property 2448 on Messages is only possible for Connections that were established 2449 enabling the Selection Property "Configure Per-Message Reliability". 2451 The following Message Properties are supported: 2453 9.1.3.1. Lifetime 2455 Name: msgLifetime 2457 Type: Numeric 2459 Default: infinite 2461 The Lifetime specifies how long a particular Message can wait to be 2462 sent to the Remote Endpoint before it is irrelevant and no longer 2463 needs to be (re-)transmitted. This is a hint to the Transport 2464 Services system - it is not guaranteed that a Message will not be 2465 sent when its Lifetime has expired. 2467 Setting a Message's Lifetime to infinite indicates that the 2468 application does not wish to apply a time constraint on the 2469 transmission of the Message, but it does not express a need for 2470 reliable delivery; reliability is adjustable per Message via the 2471 "Reliable Data Transfer (Message)" property (see Section 9.1.3.7). 2472 The type and units of Lifetime are implementation-specific. 2474 9.1.3.2. Priority 2476 Name: msgPrio 2478 Type: Integer (non-negative) 2480 Default: 100 2482 This property specifies the priority of a Message, relative to other 2483 Messages sent over the same Connection. 2485 A Message with Priority 0 will yield to a Message with Priority 1, 2486 which will yield to a Message with Priority 2, and so on. Priorities 2487 may be used as a sender-side scheduling construct only, or be used to 2488 specify priorities on the wire for Protocol Stacks supporting 2489 prioritization. 2491 Note that this property is not a per-message override of the 2492 Connection Priority - see Section 8.1.2. The Priority properties may 2493 interact, but can be used independently and be realized by different 2494 mechanisms; see Section 9.2.6. 2496 9.1.3.3. Ordered 2498 Name: msgOrdered 2500 Type: Boolean 2502 Default: the queried Boolean value of the Selection Property 2503 "preserveOrder" (Section 6.2.4) 2505 The order in which Messages were submitted for transmission via the 2506 Send Action will be preserved on delivery via Receive<> events for 2507 all Messages on a Connection that have this Message Property set to 2508 true. 2510 If false, the Message is delivered to the receiving application 2511 without preserving the ordering. This property is used for protocols 2512 that support preservation of data ordering, see Section 6.2.4, but 2513 allow out-of-order delivery for certain messages, e.g., by 2514 multiplexing independent messages onto different streams. 2516 9.1.3.4. Safely Replayable 2518 Name: safelyReplayable 2520 Type: Boolean 2522 Default: false 2524 If true, Safely Replayable specifies that a Message is safe to send 2525 to the Remote Endpoint more than once for a single Send Action. It 2526 marks the data as safe for certain 0-RTT establishment techniques, 2527 where retransmission of the 0-RTT data may cause the remote 2528 application to receive the Message multiple times. 2530 For protocols that do not protect against duplicated messages, e.g., 2531 UDP, all messages need to be marked as "Safely Replayable". To 2532 enable protocol selection to choose such a protocol, "Safely 2533 Replayable" needs to be added to the TransportProperties passed to 2534 the Preconnection. If such a protocol was chosen, disabling "Safely 2535 Replayable" on individual messages MUST result in a SendError. 2537 9.1.3.5. Final 2539 Name: final 2541 Type: Boolean 2543 Default: false 2545 If true, this indicates a Message is the last that the application 2546 will send on a Connection. This allows underlying protocols to 2547 indicate to the Remote Endpoint that the Connection has been 2548 effectively closed in the sending direction. For example, TCP-based 2549 Connections can send a FIN once a Message marked as Final has been 2550 completely sent, indicated by marking endOfMessage. Protocols that 2551 do not support signalling the end of a Connection in a given 2552 direction will ignore this property. 2554 A Final Message must always be sorted to the end of a list of 2555 Messages. The Final property overrides Priority and any other 2556 property that would re-order Messages. If another Message is sent 2557 after a Message marked as Final has already been sent on a 2558 Connection, the Send Action for the new Message will cause a 2559 SendError Event. 2561 9.1.3.6. Sending Corruption Protection Length 2563 Name: msgChecksumLen 2565 Type: Integer (non-negative with special value "Full Coverage") 2567 Default: Full Coverage 2569 This property specifies the minimum length of the section of a sent 2570 Message, starting from byte 0, that the application requires to be 2571 delivered without corruption due to lower layer errors. It is used 2572 to specify options for simple integrity protection via checksums. A 2573 value of 0 means that no checksum needs to be calculated, and "Full 2574 Coverage" means that the entire Message needs to be protected by a 2575 checksum. Only "Full Coverage" is guaranteed, any other requests are 2576 advisory, which may result in "Full Coverage" being applied. 2578 9.1.3.7. Reliable Data Transfer (Message) 2580 Name: msgReliable 2582 Type: Boolean 2584 Default: the queried Boolean value of the Selection Property 2585 "reliability" (Section 6.2.1) 2587 When true, this property specifies that a Message should be sent in 2588 such a way that the transport protocol ensures all data is received 2589 on the other side without corruption. Changing the "Reliable Data 2590 Transfer" property on Messages is only possible for Connections that 2591 were established enabling the Selection Property "Configure Per- 2592 Message Reliability". When this is not the case, changing 2593 "msgReliable" will generate an error. 2595 Disabling this property indicates that the Transport Services system 2596 may disable retransmissions or other reliability mechanisms for this 2597 particular Message, but such disabling is not guaranteed. 2599 9.1.3.8. Message Capacity Profile Override 2601 Name: msgCapacityProfile 2603 Type: Enumeration 2605 Default: inherited from the Connection Property 2606 "connCapacityProfile" (Section 8.1.6) 2608 This enumerated property specifies the application's preferred 2609 tradeoffs for sending this Message; it is a per-Message override of 2610 the Capacity Profile connection property (see Section 8.1.6). 2612 9.1.3.9. No Network-Layer Fragmentation 2614 Name: noFragmentation 2616 Type: Boolean 2618 Default: false 2620 This property specifies that a message should be sent and received 2621 without network-layer fragmentation, if possible. It can be used to 2622 avoid network layer fragmentation when transport segmentation is 2623 prefered. 2625 This only takes effect when the transport uses a network layer that 2626 supports this functionality. When it does take effect, setting this 2627 property to true will cause the sender to avoid network-layer source 2628 frgementation. When using IPv4, this will result in the Don't 2629 Fragment bit being set in the IP header. 2631 Attempts to send a message with this property that result in a size 2632 greater than the transport's current estimate of its maximum packet 2633 size ("singularTransmissionMsgMaxLen") can result in transport 2634 segmentation when permitted, or in a "SendError". 2636 Note: noSegmentation should be used when it is desired to only send a 2637 message within a single network packet. 2639 9.1.3.10. No Segmentation 2641 Name: noSegmentation 2643 Type: Boolean 2645 Default: false 2647 When set to true, this property requests the transport layer to not 2648 provide segmentation of messages larger than the maximum size 2649 permitted by the network layer, and also to avoid network-layer 2650 source fragmentation of messages. When running over IPv4, setting 2651 this property to true can result in a sending endpount setting the 2652 Don't Fragment bit in the IPv4 header of packets generated by the 2653 transport layer. An attempt to send a message that results in a size 2654 greater than the transport's current estimate of its maximum packet 2655 size (singularTransmissionMsgMaxLen) will result in a SendError. 2656 This only takes effect when the transport and network layer support 2657 this functionality. 2659 9.2. Sending Data 2661 Once a Connection has been established, it can be used for sending 2662 Messages. By default, Send enqueues a complete Message, and takes 2663 optional per-Message properties (see Section 9.2.1). All Send 2664 actions are asynchronous, and deliver Events (see Section 9.2.2). 2665 Sending partial Messages for streaming large data is also supported 2666 (see Section 9.2.3). 2668 Messages are sent on a Connection using the Send action: 2670 Connection.Send(messageData, messageContext?, endOfMessage?) 2672 where messageData is the data object to send, and messageContext 2673 allows adding Message Properties, identifying Send Events related to 2674 a specific Message or inspecting meta-data related to the Message 2675 sent (see Section 9.1.1). 2677 The optional endOfMessage parameter supports partial sending and is 2678 described in Section 9.2.3. 2680 9.2.1. Basic Sending 2682 The most basic form of sending on a connection involves enqueuing a 2683 single Data block as a complete Message with default Message 2684 Properties. 2686 messageData := "hello" 2687 Connection.Send(messageData) 2689 The interpretation of a Message to be sent is dependent on the 2690 implementation, and on the constraints on the Protocol Stacks implied 2691 by the Connection's transport properties. For example, a Message may 2692 be a single datagram for UDP Connections; or an HTTP Request for HTTP 2693 Connections. 2695 Some transport protocols can deliver arbitrarily sized Messages, but 2696 other protocols constrain the maximum Message size. Applications can 2697 query the Connection Property "Maximum Message size on send" 2698 (Section 8.1.11.3) to determine the maximum size allowed for a single 2699 Message. If a Message is too large to fit in the Maximum Message 2700 Size for the Connection, the Send will fail with a SendError event 2701 (Section 9.2.2.3). For example, it is invalid to send a Message over 2702 a UDP connection that is larger than the available datagram sending 2703 size. 2705 9.2.2. Send Events 2707 Like all Actions in this interface, the Send Action is asynchronous. 2708 There are several Events that can be delivered in response to Sending 2709 a Message. Exactly one Event (Sent, Expired, or SendError) will be 2710 delivered in response to each call to Send. 2712 Note that if partial Sends are used (Section 9.2.3), there will still 2713 be exactly one Send Event delivered for each call to Send. For 2714 example, if a Message expired while two requests to Send data for 2715 that Message are outstanding, there will be two Expired events 2716 delivered. 2718 The interface should allow the application to correlate which Send 2719 Action resulted in a particular Send Event. The manner in which this 2720 correlation is indicated is implementation-specific. 2722 9.2.2.1. Sent 2724 Connection -> Sent 2725 The Sent Event occurs when a previous Send Action has completed, 2726 i.e., when the data derived from the Message has been passed down or 2727 through the underlying Protocol Stack and is no longer the 2728 responsibility of this interface. The exact disposition of the 2729 Message (i.e., whether it has actually been transmitted, moved into a 2730 buffer on the network interface, moved into a kernel buffer, and so 2731 on) when the Sent Event occurs is implementation-specific. The Sent 2732 Event contains a reference to the Message Context of the Message to 2733 which it applies. 2735 Sent Events allow an application to obtain an understanding of the 2736 amount of buffering it creates. That is, if an application calls the 2737 Send Action multiple times without waiting for a Sent Event, it has 2738 created more buffer inside the Transport Services system than an 2739 application that always waits for the Sent Event before calling the 2740 next Send Action. 2742 9.2.2.2. Expired 2744 Connection -> Expired 2746 The Expired Event occurs when a previous Send Action expired before 2747 completion; i.e. when the Message was not sent before its Lifetime 2748 (see Section 9.1.3.1) expired. This is separate from SendError, as 2749 it is an expected behavior for partially reliable transports. The 2750 Expired Event contains a reference to the Message Context of the 2751 Message to which it applies. 2753 9.2.2.3. SendError 2755 Connection -> SendError 2757 A SendError occurs when a Message was not sent due to an error 2758 condition: an attempt to send a Message which is too large for the 2759 system and Protocol Stack to handle, some failure of the underlying 2760 Protocol Stack, or a set of Message Properties not consistent with 2761 the Connection's transport properties. The SendError contains a 2762 reference to the Message Context of the Message to which it applies. 2764 9.2.3. Partial Sends 2766 It is not always possible for an application to send all data 2767 associated with a Message in a single Send Action. The Message data 2768 may be too large for the application to hold in memory at one time, 2769 or the length of the Message may be unknown or unbounded. 2771 Partial Message sending is supported by passing an endOfMessage 2772 boolean parameter to the Send Action. This value is always true by 2773 default, and the simpler forms of Send are equivalent to passing true 2774 for endOfMessage. 2776 The following example sends a Message in two separate calls to Send. 2778 messageContext := NewMessageContext() 2779 messageContext.add(parameter, value) 2781 messageData := "hel" 2782 endOfMessage := false 2783 Connection.Send(messageData, messageContext, endOfMessage) 2785 messageData := "lo" 2786 endOfMessage := true 2787 Connection.Send(messageData, messageContext, endOfMessage) 2789 All data sent with the same MessageContext object will be treated as 2790 belonging to the same Message, and will constitute an in-order series 2791 until the endOfMessage is marked. 2793 9.2.4. Batching Sends 2795 To reduce the overhead of sending multiple small Messages on a 2796 Connection, the application could batch several Send Actions 2797 together. This provides a hint to the system that the sending of 2798 these Messages ought to be coalesced when possible, and that sending 2799 any of the batched Messages can be delayed until the last Message in 2800 the batch is enqueued. 2802 The semantics for starting and ending a batch can be implementation- 2803 specific, but need to allow multiple Send Actions to be enqueued. 2805 Connection.StartBatch() 2806 Connection.Send(messageData) 2807 Connection.Send(messageData) 2808 Connection.EndBatch() 2810 9.2.5. Send on Active Open: InitiateWithSend 2812 For application-layer protocols where the Connection initiator also 2813 sends the first message, the InitiateWithSend() action combines 2814 Connection initiation with a first Message sent: 2816 Connection := Preconnection.InitiateWithSend(messageData, messageContext?, timeout?) 2817 Whenever possible, a messageContext should be provided to declare the 2818 Message passed to InitiateWithSend as "Safely Replayable". This 2819 allows the Transport Services system to make use of 0-RTT 2820 establishment in case this is supported by the available protocol 2821 stacks. When the selected stack(s) do not support transmitting data 2822 upon connection establishment, InitiateWithSend is identical to 2823 Initiate() followed by Send(). 2825 Neither partial sends nor send batching are supported by 2826 InitiateWithSend(). 2828 The Events that may be sent after InitiateWithSend() are equivalent 2829 to those that would be sent by an invocation of Initiate() followed 2830 immediately by an invocation of Send(), with the caveat that a send 2831 failure that occurs because the Connection could not be established 2832 will not result in a SendError separate from the EstablishmentError 2833 signaling the failure of Connection establishment. 2835 9.2.6. Priority in TAPS 2837 The Transport Services interface provides two properties to allow a 2838 sender to signal the relative priority of data transmission: the 2839 Priority Message Property Section 9.1.3.2, and the Connection 2840 Priority Connection Property Section 8.1.2. These properties are 2841 designed to allow the expression and implementation of a wide variety 2842 of approaches to transmission priority in the transport and 2843 application layer, including those which do not appear on the wire 2844 (affecting only sender-side transmission scheduling) as well as those 2845 that do (e.g. [I-D.ietf-httpbis-priority]. 2847 A Transport Services system gives no guarantees about how its 2848 expression of relative priorities will be realized. However, the 2849 Transport Services system will seek to ensure that performance of 2850 relatively-prioritized connections and messages is not worse with 2851 respect to those connections and messages than an equivalent 2852 configuration in which all prioritization properties are left at 2853 their defaults. 2855 The Transport Services interface does order Connection Priority over 2856 the Priority Message Property. In the absense of other externalities 2857 (e.g., transport-layer flow control), a priority 1 Message on a 2858 priority 0 Connection will be sent before a priority 0 Message on a 2859 priority 1 Connection in the same group. 2861 9.3. Receiving Data 2863 Once a Connection is established, it can be used for receiving data 2864 (unless the "Direction of Communication" property is set to 2865 "unidirectional send"). As with sending, the data is received in 2866 Messages. Receiving is an asynchronous operation, in which each call 2867 to Receive enqueues a request to receive new data from the 2868 connection. Once data has been received, or an error is encountered, 2869 an event will be delivered to complete any pending Receive requests 2870 (see Section 9.3.2). If Messages arrive at the Transport Services 2871 system before Receive requests are issued, ensuing Receive requests 2872 will first operate on these Messages before awaiting any further 2873 Messages. 2875 9.3.1. Enqueuing Receives 2877 Receive takes two parameters to specify the length of data that an 2878 application is willing to receive, both of which are optional and 2879 have default values if not specified. 2881 Connection.Receive(minIncompleteLength?, maxLength?) 2883 By default, Receive will try to deliver complete Messages in a single 2884 event (Section 9.3.2.1). 2886 The application can set a minIncompleteLength value to indicate the 2887 smallest partial Message data size in bytes that should be delivered 2888 in response to this Receive. By default, this value is infinite, 2889 which means that only complete Messages should be delivered (see 2890 Section 9.3.2.2 and Section 9.1.2 for more information on how this is 2891 accomplished). If this value is set to some smaller value, the 2892 associated receive event will be triggered only when at least that 2893 many bytes are available, or the Message is complete with fewer 2894 bytes, or the system needs to free up memory. Applications should 2895 always check the length of the data delivered to the receive event 2896 and not assume it will be as long as minIncompleteLength in the case 2897 of shorter complete Messages or memory issues. 2899 The maxLength argument indicates the maximum size of a Message in 2900 bytes that the application is currently prepared to receive. The 2901 default value for maxLength is infinite. If an incoming Message is 2902 larger than the minimum of this size and the maximum Message size on 2903 receive for the Connection's Protocol Stack, it will be delivered via 2904 ReceivedPartial events (Section 9.3.2.2). 2906 Note that maxLength does not guarantee that the application will 2907 receive that many bytes if they are available; the interface could 2908 return ReceivedPartial events with less data than maxLength according 2909 to implementation constraints. Note also that maxLength and 2910 minIncompleteLength are intended only to manage buffering, and are 2911 not interpreted as a receiver preference for message reordering. 2913 9.3.2. Receive Events 2915 Each call to Receive will be paired with a single Receive Event, 2916 which can be a success or an error. This allows an application to 2917 provide backpressure to the transport stack when it is temporarily 2918 not ready to receive messages. 2920 The interface should allow the application to correlate which call to 2921 Receive resulted in a particular Receive Event. The manner in which 2922 this correlation is indicated is implementation-specific. 2924 9.3.2.1. Received 2926 Connection -> Received 2928 A Received event indicates the delivery of a complete Message. It 2929 contains two objects, the received bytes as messageData, and the 2930 metadata and properties of the received Message as messageContext. 2932 The messageData object provides access to the bytes that were 2933 received for this Message, along with the length of the byte array. 2934 The messageContext is provided to enable retrieving metadata about 2935 the message and referring to the message, e.g., to send replies and 2936 map responses to their requests. See Section 9.1.1 for details. 2938 See Section 9.1.2 for handling Message framing in situations where 2939 the Protocol Stack only provides a byte-stream transport. 2941 9.3.2.2. ReceivedPartial 2943 Connection -> ReceivedPartial 2945 If a complete Message cannot be delivered in one event, one part of 2946 the Message can be delivered with a ReceivedPartial event. To 2947 continue to receive more of the same Message, the application must 2948 invoke Receive again. 2950 Multiple invocations of ReceivedPartial deliver data for the same 2951 Message by passing the same MessageContext, until the endOfMessage 2952 flag is delivered or a ReceiveError occurs. All partial blocks of a 2953 single Message are delivered in order without gaps. This event does 2954 not support delivering discontiguous partial Messages. If, for 2955 example, Message A is divided into three pieces (A1, A2, A3) and 2956 Message B is divided into three pieces (B1, B2, B3), and 2957 preserveOrder is not Required, the ReceivedPartial may deliver them 2958 in a sequence like this: A1, B1, B2, A2, A3, B3, because the 2959 messageContext allows the application to identify the pieces as 2960 belonging to Message A and B, respectively. However, a sequence 2961 like: A1, A3 will never occur. 2963 If the minIncompleteLength in the Receive request was set to be 2964 infinite (indicating a request to receive only complete Messages), 2965 the ReceivedPartial event may still be delivered if one of the 2966 following conditions is true: 2968 * the underlying Protocol Stack supports message boundary 2969 preservation, and the size of the Message is larger than the 2970 buffers available for a single message; 2972 * the underlying Protocol Stack does not support message boundary 2973 preservation, and the Message Framer (see Section 9.1.2) cannot 2974 determine the end of the message using the buffer space it has 2975 available; or 2977 * the underlying Protocol Stack does not support message boundary 2978 preservation, and no Message Framer was supplied by the 2979 application 2981 Note that in the absence of message boundary preservation or a 2982 Message Framer, all bytes received on the Connection will be 2983 represented as one large Message of indeterminate length. 2985 9.3.2.3. ReceiveError 2987 Connection -> ReceiveError 2989 A ReceiveError occurs when data is received by the underlying 2990 Protocol Stack that cannot be fully retrieved or parsed, and when it 2991 is useful for the application to be notified of such errors. For 2992 example, a ReceiveError can indicate that a Message (identified via 2993 the MessageContext) that was being partially received previously, but 2994 had not completed, encountered an error and will not be completed. 2995 This can be useful for an application, which may want to use this 2996 error as a hint to remove previously received Message parts from 2997 memory. As another example, if an incoming Message does not fulfill 2998 the Required Minimum Corruption Protection Coverage for Receiving 2999 property (see Section 8.1.1), an application can use this error as a 3000 hint to inform the peer application to adjust the Sending Corruption 3001 Protection Length property (see Section 9.1.3.6). 3003 In contrast, internal protocol reception errors (e.g., loss causing 3004 retransmissions in TCP) are not signalled by this Event. Conditions 3005 that irrevocably lead to the termination of the Connection are 3006 signaled using ConnectionError (see Section 10). 3008 9.3.3. Receive Message Properties 3010 Each Message Context may contain metadata from protocols in the 3011 Protocol Stack; which metadata is available is Protocol Stack 3012 dependent. These are exposed through additional read-only Message 3013 Properties that can be queried from the MessageContext object (see 3014 Section 9.1.1) passed by the receive event. The following metadata 3015 values are supported: 3017 9.3.3.1. UDP(-Lite)-specific Property: ECN 3019 When available, Message metadata carries the value of the Explicit 3020 Congestion Notification (ECN) field. This information can be used 3021 for logging and debugging, and for building applications that need 3022 access to information about the transport internals for their own 3023 operation. This property is specific to UDP and UDP-Lite because 3024 these protocols do not implement congestion control, and hence expose 3025 this functionality to the application (see [RFC8293], following the 3026 guidance in [RFC8085]) 3028 9.3.3.2. Early Data 3030 In some cases it can be valuable to know whether data was read as 3031 part of early data transfer (before connection establishment has 3032 finished). This is useful if applications need to treat early data 3033 separately, e.g., if early data has different security properties 3034 than data sent after connection establishment. In the case of TLS 3035 1.3, client early data can be replayed maliciously (see [RFC8446]). 3036 Thus, receivers might wish to perform additional checks for early 3037 data to ensure it is safely replayable. If TLS 1.3 is available and 3038 the recipient Message was sent as part of early data, the 3039 corresponding metadata carries a flag indicating as such. If early 3040 data is enabled, applications should check this metadata field for 3041 Messages received during connection establishment and respond 3042 accordingly. 3044 9.3.3.3. Receiving Final Messages 3046 The Message Context can indicate whether or not this Message is the 3047 Final Message on a Connection. For any Message that is marked as 3048 Final, the application can assume that there will be no more Messages 3049 received on the Connection once the Message has been completely 3050 delivered. This corresponds to the Final property that may be marked 3051 on a sent Message, see Section 9.1.3.5. 3053 Some transport protocols and peers do not support signaling of the 3054 Final property. Applications therefore should not rely on receiving 3055 a Message marked Final to know that the sending endpoint is done 3056 sending on a connection. 3058 Any calls to Receive once the Final Message has been delivered will 3059 result in errors. 3061 10. Connection Termination 3063 A Connection can be terminated i) by the Local Endpoint (i.e., the 3064 application calls the Close, CloseGroup, Abort or AbortGroup Action), 3065 ii) by the Remote Endpoint (i.e., the remote application calls the 3066 Close, CloseGroup, Abort or AbortGroup Action), or iii) because of an 3067 error (e.g., a timeout). A local call of the Close Action will cause 3068 the Connection to either send a Closed Event or a ConnectionError 3069 Event, and a local call of the CloseGroup Action will cause all of 3070 the Connections in the group to either send a Closed Event or a 3071 ConnectionError Event. A local call of the Abort Action will cause 3072 the Connection to send a ConnectionError Event, indicating local 3073 Abort as a reason, and a local call of the AbortGroup Action will 3074 cause all of the Connections in the group to send a ConnectionError 3075 Event, indicating local Abort as a reason. 3077 Remote Action calls map to Events similar to local calls (e.g., a 3078 remote Close causes the Connection to either send a Closed Event or a 3079 ConnectionError Event), but, different from local Action calls, it is 3080 not guaranteed that such Events will indeed be invoked. When an 3081 application needs to free resources associated with a Connection, it 3082 should therefore not rely on the invocation of such Events due to 3083 termination calls from the Remote Endpoint, but instead use the local 3084 termination Actions. 3086 Close terminates a Connection after satisfying all the requirements 3087 that were specified regarding the delivery of Messages that the 3088 application has already given to the Transport Services system. Upon 3089 successfully satisfying all these requirements, the Connection will 3090 send the Closed Event. For example, if reliable delivery was 3091 requested for a Message handed over before calling Close, the Closed 3092 Event will signify that this Message has indeed been delivered. This 3093 Action does not affect any other Connection in the same Connection 3094 Group. 3096 Connection.Close() 3098 The Closed Event informs the application that a Close Action has 3099 successfully completed, or that the Remote Endpoint has closed the 3100 Connection. There is no guarantee that a remote Close will be 3101 signaled. 3103 Connection -> Closed<> 3105 Abort terminates a Connection without delivering any remaining 3106 Messages. This action does not affect any other Connection that is 3107 entangled with this one in a Connection Group. When the Abort Action 3108 has finished, the Connection will send a ConnectionError Event, 3109 indicating local Abort as a reason. 3111 Connection.Abort() 3113 CloseGroup gracefully terminates a Connection and any other 3114 Connections in the same Connection Group. For example, all of the 3115 Connections in a group might be streams of a single session for a 3116 multistreaming protocol; closing the entire group will close the 3117 underlying session. See also Section 7.4. All Connections in the 3118 group will send a Closed Event when the CloseGroup Action was 3119 successful. As with Close, any Messages remaining to be processed on 3120 a Connection will be handled prior to closing. 3122 Connection.CloseGroup() 3124 AbortGroup terminates a Connection and any other Connections that are 3125 in the same Connection Group without delivering any remaining 3126 Messages. When the AbortGroup Action has finished, all Connections 3127 in the group will send a ConnectionError Event, indicating local 3128 Abort as a reason. 3130 Connection.AbortGroup() 3132 A ConnectionError informs the application that: 1) data could not be 3133 delivered to the peer after a timeout, or 2) the Connection has been 3134 aborted (e.g., because the peer has called Abort). There is no 3135 guarantee that an Abort from the peer will be signaled. 3137 Connection -> ConnectionError 3139 11. Connection State and Ordering of Operations and Events 3141 This interface is designed to be independent of an implementation's 3142 concurrency model. The details of how exactly actions are handled, 3143 and how events are dispatched, are implementation dependent. 3145 Each transition of connection state is associated with one of more 3146 events: 3148 * Ready<> occurs when a Connection created with Initiate() or 3149 InitiateWithSend() transitions to Established state. 3151 * ConnectionReceived<> occurs when a Connection created with 3152 Listen() transitions to Established state. 3154 * RendezvousDone<> occurs when a Connection created with 3155 Rendezvous() transitions to Established state. 3157 * Closed<> occurs when a Connection transitions to Closed state 3158 without error. 3160 * EstablishmentError<> occurs when a Connection created with 3161 Initiate() transitions from Establishing state to Closed state due 3162 to an error. 3164 * ConnectionError<> occurs when a Connection transitions to Closed 3165 state due to an error in all other circumstances. 3167 The following diagram shows the possible states of a Connection and 3168 the events that occur upon a transition from one state to another. 3170 (*) (**) 3171 Establishing -----> Established -----> Closing ------> Closed 3172 | ^ 3173 | | 3174 +---------------------------------------------------+ 3175 EstablishmentError<> 3177 (*) Ready<>, ConnectionReceived<>, RendezvousDone<> 3178 (**) Closed<>, ConnectionError<> 3180 Figure 2: Connection State Diagram 3182 The interface provides the following guarantees about the ordering of 3183 operations: 3185 * Sent<> events will occur on a Connection in the order in which the 3186 Messages were sent (i.e., delivered to the kernel or to the 3187 network interface, depending on implementation). 3189 * Received<> will never occur on a Connection before it is 3190 Established; i.e. before a Ready<> event on that Connection, or a 3191 ConnectionReceived<> or RendezvousDone<> containing that 3192 Connection. 3194 * No events will occur on a Connection after it is Closed; i.e., 3195 after a Closed<> event, an EstablishmentError<> or 3196 ConnectionError<> will not occur on that connection. To ensure 3197 this ordering, Closed<> will not occur on a Connection while other 3198 events on the Connection are still locally outstanding (i.e., 3199 known to the interface and waiting to be dealt with by the 3200 application). 3202 12. IANA Considerations 3204 RFC-EDITOR: Please remove this section before publication. 3206 This document has no Actions for IANA. Later versions of this 3207 document may create IANA registries for generic transport property 3208 names and transport property namespaces (see Section 4.1). 3210 13. Privacy and Security Considerations 3212 This document describes a generic API for interacting with a 3213 transport services (TAPS) system. Part of this API includes 3214 configuration details for transport security protocols, as discussed 3215 in Section 6.3. It does not recommend use (or disuse) of specific 3216 algorithms or protocols. Any API-compatible transport security 3217 protocol ought to work in a TAPS system. Security considerations for 3218 these protocols are discussed in the respective specifications. 3220 The described API is used to exchange information between an 3221 application and the Transport Services system. While it is not 3222 necessarily expected that both systems are implemented by the same 3223 authority, it is expected that the Transport Services system 3224 implementation is either provided as a library that is selected by 3225 the application from a trusted party, or that it is part of the 3226 operating system that the application also relies on for other tasks. 3228 In either case, the Transport Services API is an internal interface 3229 that is used to change information locally between two systems. 3230 However, as the Transport Services system is responsible for network 3231 communication, it is in the position to potentially share any 3232 information provided by the application with the network or another 3233 communication peer. Most of the information provided over the 3234 Transport Services API are useful to configure and select protocols 3235 and paths and are not necessarily privacy sensitive. Still, some 3236 information could be privacy sensitive because it might reveal usage 3237 characteristics and habits of the user of an application. 3239 Of course any communication over a network reveals usage 3240 characteristics, as all packets, as well as their timing and size, 3241 are part of the network-visible wire image [RFC8546]. However, the 3242 selection of a protocol and its configuration also impacts which 3243 information is visible, potentially in clear text, and which other 3244 entities can access it. In most cases, information provided for 3245 protocol and path selection should not directly translate to 3246 information that can be observed by network devices on the path. 3247 However, there might be specific configuration information that is 3248 intended for path exposure, e.g., a DiffServ codepoint setting, that 3249 is either provided directly by the application or indirectly 3250 configured for a traffic profile. 3252 Applications should be aware that communication attempts can lead to 3253 more than one connection establishment. This is the case, for 3254 example, when the Transport Services system also executes name 3255 resolution, when support mechanisms such as TURN or ICE are used to 3256 establish connectivity, if protocols or paths are raised, or if a 3257 path fails and fallback or re-establishment is supported in the 3258 Transport Services system. 3260 Applications should also take care to not assume that all data 3261 received using the Transport Services API is always complete or well- 3262 formed. Specifically, messages that are received partially 3263 Section 9.3.2.2 could be a source of truncation attacks if 3264 applications do not distinguish between partial messages and complete 3265 messages. 3267 The interface explicitly does not require the application to resolve 3268 names, though there is a tradeoff between early and late binding of 3269 addresses to names. Early binding allows the API implementation to 3270 reduce connection setup latency, at the cost of potentially limited 3271 scope for alternate path discovery during Connection establishment, 3272 as well as potential additional information leakage about application 3273 interest when used with a resolution method (such as DNS without TLS) 3274 which does not protect query confidentiality. 3276 These communication activities are not different from what is used 3277 today. However, the goal of a Transport Services system is to 3278 support such mechanisms as a generic service within the transport 3279 layer. This enables applications to more dynamically benefit from 3280 innovations and new protocols in the transport, although it reduces 3281 transparency of the underlying communication actions to the 3282 application itself. The TAPS API is designed such that protocol and 3283 path selection can be limited to a small and controlled set if 3284 required by the application for functional or security purposes. 3285 Further, TAPS implementations should provide an interface to poll 3286 information about which protocol and path is currently in use as well 3287 as provide logging about the communication events of each connection. 3289 14. Acknowledgements 3291 This work has received funding from the European Union's Horizon 2020 3292 research and innovation programme under grant agreements No. 644334 3293 (NEAT) and No. 688421 (MAMI). 3295 This work has been supported by Leibniz Prize project funds of DFG - 3296 German Research Foundation: Gottfried Wilhelm Leibniz-Preis 2011 (FKZ 3297 FE 570/4-1). 3299 This work has been supported by the UK Engineering and Physical 3300 Sciences Research Council under grant EP/R04144X/1. 3302 This work has been supported by the Research Council of Norway under 3303 its "Toppforsk" programme through the "OCARINA" project. 3305 Thanks to Stuart Cheshire, Josh Graessley, David Schinazi, and Eric 3306 Kinnear for their implementation and design efforts, including Happy 3307 Eyeballs, that heavily influenced this work. Thanks to Laurent Chuat 3308 and Jason Lee for initial work on the Post Sockets interface, from 3309 which this work has evolved. Thanks to Maximilian Franke for asking 3310 good questions based on implementation experience and for 3311 contributing text, e.g., on multicast. 3313 15. References 3315 15.1. Normative References 3317 [I-D.ietf-taps-arch] 3318 Pauly, T., Trammell, B., Brunstrom, A., Fairhurst, G., 3319 Perkins, C., Tiesel, P. S., and C. A. Wood, "An 3320 Architecture for Transport Services", Work in Progress, 3321 Internet-Draft, draft-ietf-taps-arch-10, 30 April 2021, 3322 . 3325 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3326 Requirement Levels", BCP 14, RFC 2119, 3327 DOI 10.17487/RFC2119, March 1997, 3328 . 3330 [RFC2914] Floyd, S., "Congestion Control Principles", BCP 41, 3331 RFC 2914, DOI 10.17487/RFC2914, September 2000, 3332 . 3334 [RFC4941] Narten, T., Draves, R., and S. Krishnan, "Privacy 3335 Extensions for Stateless Address Autoconfiguration in 3336 IPv6", RFC 4941, DOI 10.17487/RFC4941, September 2007, 3337 . 3339 [RFC8084] Fairhurst, G., "Network Transport Circuit Breakers", 3340 BCP 208, RFC 8084, DOI 10.17487/RFC8084, March 2017, 3341 . 3343 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 3344 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 3345 March 2017, . 3347 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3348 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3349 May 2017, . 3351 [RFC8303] Welzl, M., Tuexen, M., and N. Khademi, "On the Usage of 3352 Transport Features Provided by IETF Transport Protocols", 3353 RFC 8303, DOI 10.17487/RFC8303, February 2018, 3354 . 3356 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3357 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3358 . 3360 15.2. Informative References 3362 [I-D.ietf-httpbis-priority] 3363 Oku, K. and L. Pardue, "Extensible Prioritization Scheme 3364 for HTTP", Work in Progress, Internet-Draft, draft-ietf- 3365 httpbis-priority-03, 11 January 2021, 3366 . 3369 [I-D.ietf-taps-impl] 3370 Brunstrom, A., Pauly, T., Enghardt, T., Grinnemo, K., 3371 Jones, T., Tiesel, P. S., Perkins, C., and M. Welzl, 3372 "Implementing Interfaces to Transport Services", Work in 3373 Progress, Internet-Draft, draft-ietf-taps-impl-09, 30 3374 April 2021, . 3377 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 3378 "Definition of the Differentiated Services Field (DS 3379 Field) in the IPv4 and IPv6 Headers", RFC 2474, 3380 DOI 10.17487/RFC2474, December 1998, 3381 . 3383 [RFC2597] Heinanen, J., Baker, F., Weiss, W., and J. Wroclawski, 3384 "Assured Forwarding PHB Group", RFC 2597, 3385 DOI 10.17487/RFC2597, June 1999, 3386 . 3388 [RFC3246] Davie, B., Charny, A., Bennet, J.C.R., Benson, K., Le 3389 Boudec, J.Y., Courtney, W., Davari, S., Firoiu, V., and D. 3390 Stiliadis, "An Expedited Forwarding PHB (Per-Hop 3391 Behavior)", RFC 3246, DOI 10.17487/RFC3246, March 2002, 3392 . 3394 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 3395 A., Peterson, J., Sparks, R., Handley, M., and E. 3396 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 3397 DOI 10.17487/RFC3261, June 2002, 3398 . 3400 [RFC4594] Babiarz, J., Chan, K., and F. Baker, "Configuration 3401 Guidelines for DiffServ Service Classes", RFC 4594, 3402 DOI 10.17487/RFC4594, August 2006, 3403 . 3405 [RFC5245] Rosenberg, J., "Interactive Connectivity Establishment 3406 (ICE): A Protocol for Network Address Translator (NAT) 3407 Traversal for Offer/Answer Protocols", RFC 5245, 3408 DOI 10.17487/RFC5245, April 2010, 3409 . 3411 [RFC5482] Eggert, L. and F. Gont, "TCP User Timeout Option", 3412 RFC 5482, DOI 10.17487/RFC5482, March 2009, 3413 . 3415 [RFC5766] Mahy, R., Matthews, P., and J. Rosenberg, "Traversal Using 3416 Relays around NAT (TURN): Relay Extensions to Session 3417 Traversal Utilities for NAT (STUN)", RFC 5766, 3418 DOI 10.17487/RFC5766, April 2010, 3419 . 3421 [RFC5865] Baker, F., Polk, J., and M. Dolly, "A Differentiated 3422 Services Code Point (DSCP) for Capacity-Admitted Traffic", 3423 RFC 5865, DOI 10.17487/RFC5865, May 2010, 3424 . 3426 [RFC7478] Holmberg, C., Hakansson, S., and G. Eriksson, "Web Real- 3427 Time Communication Use Cases and Requirements", RFC 7478, 3428 DOI 10.17487/RFC7478, March 2015, 3429 . 3431 [RFC7556] Anipko, D., Ed., "Multiple Provisioning Domain 3432 Architecture", RFC 7556, DOI 10.17487/RFC7556, June 2015, 3433 . 3435 [RFC7657] Black, D., Ed. and P. Jones, "Differentiated Services 3436 (Diffserv) and Real-Time Communication", RFC 7657, 3437 DOI 10.17487/RFC7657, November 2015, 3438 . 3440 [RFC8095] Fairhurst, G., Ed., Trammell, B., Ed., and M. Kuehlewind, 3441 Ed., "Services Provided by IETF Transport Protocols and 3442 Congestion Control Mechanisms", RFC 8095, 3443 DOI 10.17487/RFC8095, March 2017, 3444 . 3446 [RFC8229] Pauly, T., Touati, S., and R. Mantha, "TCP Encapsulation 3447 of IKE and IPsec Packets", RFC 8229, DOI 10.17487/RFC8229, 3448 August 2017, . 3450 [RFC8260] Stewart, R., Tuexen, M., Loreto, S., and R. Seggelmann, 3451 "Stream Schedulers and User Message Interleaving for the 3452 Stream Control Transmission Protocol", RFC 8260, 3453 DOI 10.17487/RFC8260, November 2017, 3454 . 3456 [RFC8293] Ghanwani, A., Dunbar, L., McBride, M., Bannai, V., and R. 3457 Krishnan, "A Framework for Multicast in Network 3458 Virtualization over Layer 3", RFC 8293, 3459 DOI 10.17487/RFC8293, January 2018, 3460 . 3462 [RFC8489] Petit-Huguenin, M., Salgueiro, G., Rosenberg, J., Wing, 3463 D., Mahy, R., and P. Matthews, "Session Traversal 3464 Utilities for NAT (STUN)", RFC 8489, DOI 10.17487/RFC8489, 3465 February 2020, . 3467 [RFC8546] Trammell, B. and M. Kuehlewind, "The Wire Image of a 3468 Network Protocol", RFC 8546, DOI 10.17487/RFC8546, April 3469 2019, . 3471 [RFC8622] Bless, R., "A Lower-Effort Per-Hop Behavior (LE PHB) for 3472 Differentiated Services", RFC 8622, DOI 10.17487/RFC8622, 3473 June 2019, . 3475 [RFC8699] Islam, S., Welzl, M., and S. Gjessing, "Coupled Congestion 3476 Control for RTP Media", RFC 8699, DOI 10.17487/RFC8699, 3477 January 2020, . 3479 [RFC8899] Fairhurst, G., Jones, T., Tüxen, M., Rüngeler, I., and T. 3480 Völker, "Packetization Layer Path MTU Discovery for 3481 Datagram Transports", RFC 8899, DOI 10.17487/RFC8899, 3482 September 2020, . 3484 [RFC8922] Enghardt, T., Pauly, T., Perkins, C., Rose, K., and C. 3485 Wood, "A Survey of the Interaction between Security 3486 Protocols and Transport Services", RFC 8922, 3487 DOI 10.17487/RFC8922, October 2020, 3488 . 3490 [RFC8923] Welzl, M. and S. Gjessing, "A Minimal Set of Transport 3491 Services for End Systems", RFC 8923, DOI 10.17487/RFC8923, 3492 October 2020, . 3494 [TCP-COUPLING] 3495 Islam, S., Welzl, M., Hiorth, K., Hayes, D., Armitage, G., 3496 and S. Gjessing, "ctrlTCP: Reducing Latency through 3497 Coupled, Heterogeneous Multi-Flow TCP Congestion Control", 3498 IEEE INFOCOM Global Internet Symposium (GI) workshop (GI 3499 2018) , 2018. 3501 Appendix A. Implementation Mapping 3503 The way the concepts from this abstract interface map into concrete 3504 APIs in a given language on a given platform largely depends on the 3505 features and norms of the language and the platform. Actions could 3506 be implemented as functions or method calls, for instance, and Events 3507 could be implemented via event queues, handler functions or classes, 3508 communicating sequential processes, or other asynchronous calling 3509 conventions. 3511 A.1. Types 3513 The basic types mentioned in Section 1.1 typically have natural 3514 correspondences in practical programming languages, perhaps 3515 constrained by implementation-specific limitations. For example: 3517 * An Integer can typically be represented in C by an "int" or 3518 "long", subject to the underlying platform's ranges for each. To 3519 accommodate special values, a C function that returns a non- 3520 negative "int" on success may return -1 on failure. In Python, 3521 such a function might return "None" or raise an exception. 3523 * In C, a Tuple may be represented as a "struct" with one member for 3524 each of the value types in the ordered grouping. In Python, by 3525 contrast, a Tuple may be represented natively as a "tuple", a 3526 sequence of dynamically-typed elements. 3528 * A Collection may be represented as a "std::set" in C++ or as a 3529 "set" in Python. In C, it may be represented as an array or as a 3530 higher-level data structure with appropriate accessors defined. 3532 The objects described in Section 1.1 can similarly be represented in 3533 different ways depending on which programming language is used. 3534 Objects like Preconnections, Connections, and Listeners can be long- 3535 lived, and benefit from using object-oriented constructs. Note that 3536 in C, these objects may need to provide a way to release or free 3537 their underlying memory when the application is done using them. For 3538 example, since a Preconnection can be used to initiate multiple 3539 Connections, it is the responsibility of the application to clean up 3540 the Preconnection memory if necessary. 3542 A.2. Events and Errors 3544 This specification treats Events and Errors similarly. Errors, just 3545 as any other Events, may occur asynchronously in network 3546 applications. However, implementations of this interface may report 3547 Errors synchronously, according to the error handling idioms of the 3548 implementation platform, where they can be immediately detected, such 3549 as by generating an exception when attempting to initiate a 3550 connection with inconsistent Transport Properties. An error can 3551 provide an optional reason to the application with further details 3552 about why the error occurred. 3554 A.3. Time Duration 3556 Time duration types are implementation-specific. For instance, it 3557 could be a number of seconds, number of milliseconds, or a "struct 3558 timeval" in C or a user-defined "Duration" class in C++. 3560 Appendix B. Convenience Functions 3562 B.1. Adding Preference Properties 3564 As Selection Properties of type "Preference" will be set on a 3565 TransportProperties object quite frequently, implementations can 3566 provide special actions for adding each preference level i.e, 3567 "TransportProperties.Set(some_property, avoid)" is equivalent to 3568 "TransportProperties.Avoid(some_property)": 3570 TransportProperties.Require(property) 3571 TransportProperties.Prefer(property) 3572 TransportProperties.Ignore(property) 3573 TransportProperties.Avoid(property) 3574 TransportProperties.Prohibit(property) 3576 B.2. Transport Property Profiles 3578 To ease the use of the interface specified by this document, 3579 implementations can provide a mechanism to create Transport Property 3580 objects (see Section 6.2) that are pre-configured with frequently 3581 used sets of properties; the following are in common use in current 3582 applications: 3584 B.2.1. reliable-inorder-stream 3586 This profile provides reliable, in-order transport service with 3587 congestion control. TCP is an example of a protocol that provides 3588 this service. It should consist of the following properties: 3590 +=======================+=========+ 3591 | Property | Value | 3592 +=======================+=========+ 3593 | reliability | require | 3594 +-----------------------+---------+ 3595 | preserveOrder | require | 3596 +-----------------------+---------+ 3597 | congestionControl | require | 3598 +-----------------------+---------+ 3599 | preserveMsgBoundaries | ignore | 3600 +-----------------------+---------+ 3602 Table 2: reliable-inorder- 3603 stream preferences 3605 B.2.2. reliable-message 3607 This profile provides message-preserving, reliable, in-order 3608 transport service with congestion control. SCTP is an example of a 3609 protocol that provides this service. It should consist of the 3610 following properties: 3612 +=======================+=========+ 3613 | Property | Value | 3614 +=======================+=========+ 3615 | reliability | require | 3616 +-----------------------+---------+ 3617 | preserveOrder | require | 3618 +-----------------------+---------+ 3619 | congestionControl | require | 3620 +-----------------------+---------+ 3621 | preserveMsgBoundaries | require | 3622 +-----------------------+---------+ 3624 Table 3: reliable-message 3625 preferences 3627 B.2.3. unreliable-datagram 3629 This profile provides a datagram transport service without any 3630 reliability guarantee. An example of a protocol that provides this 3631 service is UDP. It consists of the following properties: 3633 +=======================+=========+ 3634 | Property | Value | 3635 +=======================+=========+ 3636 | reliability | avoid | 3637 +-----------------------+---------+ 3638 | preserveOrder | avoid | 3639 +-----------------------+---------+ 3640 | congestionControl | ignore | 3641 +-----------------------+---------+ 3642 | preserveMsgBoundaries | require | 3643 +-----------------------+---------+ 3644 | safely replayable | true | 3645 +-----------------------+---------+ 3647 Table 4: unreliable-datagram 3648 preferences 3650 Applications that choose this Transport Property Profile would avoid 3651 the additional latency that could be introduced by retransmission or 3652 reordering in a transport protocol. 3654 Applications that choose this Transport Property Profile to reduce 3655 latency should also consider setting an appropriate Capacity Profile 3656 Property, see Section 8.1.6 and might benefit from controlling 3657 checksum coverage, see Section 6.2.7 and Section 6.2.8. 3659 Appendix C. Relationship to the Minimal Set of Transport Services for 3660 End Systems 3662 [RFC8923] identifies a minimal set of transport services that end 3663 systems should offer. These services make all non-security-related 3664 transport features of TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT 3665 available that 1) require interaction with the application, and 2) do 3666 not get in the way of a possible implementation over TCP (or, with 3667 limitations, UDP). The following text explains how this minimal set 3668 is reflected in the present API. For brevity, it is based on the 3669 list in Section 4.1 of [RFC8923], updated according to the discussion 3670 in Section 5 of [RFC8923]. The present API covers all elements of 3671 this section except "Notification of Excessive Retransmissions (early 3672 warning below abortion threshold)". This list is a subset of the 3673 transport features in Appendix A of [RFC8923], which refers to the 3674 primitives in "pass 2" (Section 4) of [RFC8303] for further details 3675 on the implementation with TCP, MPTCP, UDP, UDP-Lite, SCTP and 3676 LEDBAT. 3678 * Connect: "Initiate" Action (Section 7.1). 3680 * Listen: "Listen" Action (Section 7.2). 3682 * Specify number of attempts and/or timeout for the first 3683 establishment message: "timeout" parameter of "Initiate" 3684 (Section 7.1) or "InitiateWithSend" Action (Section 9.2.5). 3686 * Disable MPTCP: "Multipath Transport" Property (Section 6.2.14). 3688 * Hand over a message to reliably transfer (possibly multiple times) 3689 before connection establishment: "InitiateWithSend" Action 3690 (Section 9.2.5). 3692 * Change timeout for aborting connection (using retransmit limit or 3693 time value): "Timeout for Aborting Connection" property, using a 3694 time value (Section 8.1.3). 3696 * Timeout event when data could not be delivered for too long: 3697 "ConnectionError" Event (Section 10). 3699 * Suggest timeout to the peer: "TCP-specific Properties: User 3700 Timeout Option (UTO)" (Section 8.2). 3702 * Notification of ICMP error message arrival: "Notification of ICMP 3703 soft error message arrival" property (Section 6.2.17). 3705 * Choose a scheduler to operate between streams of an association: 3706 "Connection Group Transmission Scheduler" property 3707 (Section 8.1.5). 3709 * Configure priority or weight for a scheduler: "Connection 3710 Priority" property (Section 8.1.2). 3712 * "Specify checksum coverage used by the sender" and "Disable 3713 checksum when sending": "Sending Corruption Protection Length" 3714 property (Section 9.1.3.6) and "Full Checksum Coverage on Sending" 3715 property (Section 6.2.7). 3717 * "Specify minimum checksum coverage required by receiver" and 3718 "Disable checksum requirement when receiving": "Required Minimum 3719 Corruption Protection Coverage for Receiving" property 3720 (Section 8.1.1) and "Full Checksum Coverage on Receiving" property 3721 (Section 6.2.8). 3723 * "Specify DF field": "No Network-Layer Fragmentation" property 3724 (Section 9.1.3.9). 3726 * Get max. transport-message size that may be sent using a non- 3727 fragmented IP packet from the configured interface: "Maximum 3728 Message Size Before Fragmentation or Segmentation" property 3729 (Section 8.1.11.2). 3731 * Get max. transport-message size that may be received from the 3732 configured interface: "Maximum Message Size on Receive" property 3733 (Section 8.1.11.4). 3735 * Obtain ECN field: "UDP(-Lite)-specific Property: ECN" is a read- 3736 only Message Property of the MessageContext object 3737 (Section 9.3.3.1). 3739 * "Specify DSCP field", "Disable Nagle algorithm", "Enable and 3740 configure a "Low Extra Delay Background Transfer"": as suggested 3741 in Section 5.5 of [RFC8923], these transport features are 3742 collectively offered via the "Capacity Profile" property 3743 (Section 8.1.6). Per-Message control ("Request not to bundle 3744 messages") is offered via the "Message Capacity Profile Override" 3745 property (Section 9.1.3.8). 3747 * Close after reliably delivering all remaining data, causing an 3748 event informing the application on the other side: this is offered 3749 by the "Close" Action with slightly changed semantics in line with 3750 the discussion in Section 5.2 of [RFC8923] (Section 10). 3752 * "Abort without delivering remaining data, causing an event 3753 informing the application on the other side" and "Abort without 3754 delivering remaining data, not causing an event informing the 3755 application on the other side": this is offered by the "Abort" 3756 action without promising that this is signaled to the other side. 3757 If it is, a "ConnectionError" Event will fire at the peer 3758 (Section 10). 3760 * "Reliably transfer data, with congestion control", "Reliably 3761 transfer a message, with congestion control" and "Unreliably 3762 transfer a message": data is transferred via the "Send" action 3763 (Section 9.2). Reliability is controlled via the "Reliable Data 3764 Transfer (Connection)" (Section 6.2.1) property and the "Reliable 3765 Data Transfer (Message)" Message Property (Section 9.1.3.7). 3766 Transmitting data as a message or without delimiters is controlled 3767 via Message Framers (Section 9.1.2). The choice of congestion 3768 control is provided via the "Congestion control" property 3769 (Section 6.2.9). 3771 * Configurable Message Reliability: the "Lifetime" Message Property 3772 implements a time-based way to configure message reliability 3773 (Section 9.1.3.1). 3775 * "Ordered message delivery (potentially slower than unordered)" and 3776 "Unordered message delivery (potentially faster than ordered)": 3777 these two transport features are controlled via the Message 3778 Property "Ordered" (Section 9.1.3.3). 3780 * Request not to delay the acknowledgement (SACK) of a message: 3781 should the protocol support it, this is one of the transport 3782 features the Transport Services system can apply when an 3783 application uses the "Capacity Profile" Property (Section 8.1.6) 3784 or the "Message Capacity Profile Override" Message Property 3785 (Section 9.1.3.8) with value "Low Latency/Interactive". 3787 * Receive data (with no message delimiting): "Receive" Action 3788 (Section 9.3) and "Received" Event (Section 9.3.2.1). 3790 * Receive a message: "Receive" Action (Section 9.3) and "Received" 3791 Event (Section 9.3.2.1), using Message Framers (Section 9.1.2). 3793 * Information about partial message arrival: "Receive" Action 3794 (Section 9.3) and "ReceivedPartial" Event (Section 9.3.2.2). 3796 * Notification of send failures: "Expired" Event (Section 9.2.2.2) 3797 and "SendError" Event (Section 9.2.2.3). 3799 * Notification that the stack has no more user data to send: 3800 applications can obtain this information via the "Sent" Event 3801 (Section 9.2.2.1). 3803 * Notification to a receiver that a partial message delivery has 3804 been aborted: "ReceiveError" Event (Section 9.3.2.3). 3806 Authors' Addresses 3808 Brian Trammell (editor) 3809 Google Switzerland GmbH 3810 Gustav-Gull-Platz 1 3811 CH- 8004 Zurich 3812 Switzerland 3814 Email: ietf@trammell.ch 3816 Michael Welzl (editor) 3817 University of Oslo 3818 PO Box 1080 Blindern 3819 0316 Oslo 3820 Norway 3822 Email: michawe@ifi.uio.no 3824 Theresa Enghardt 3825 Netflix 3826 121 Albright Way 3827 Los Gatos, CA 95032, 3828 United States of America 3830 Email: ietf@tenghardt.net 3832 Godred Fairhurst 3833 University of Aberdeen 3834 Fraser Noble Building 3835 Aberdeen, AB24 3UE 3837 Email: gorry@erg.abdn.ac.uk 3838 URI: http://www.erg.abdn.ac.uk/ 3840 Mirja Kuehlewind 3841 Ericsson 3842 Ericsson-Allee 1 3843 Herzogenrath 3844 Germany 3846 Email: mirja.kuehlewind@ericsson.com 3848 Colin Perkins 3849 University of Glasgow 3850 School of Computing Science 3851 Glasgow G12 8QQ 3852 United Kingdom 3854 Email: csp@csperkins.org 3856 Philipp S. Tiesel 3857 SAP SE 3858 Konrad-Zuse-Ring 10 3859 14469 Potsdam 3860 Germany 3862 Email: philipp@tiesel.net 3864 Christopher A. Wood 3865 Cloudflare 3866 101 Townsend St 3867 San Francisco, 3868 United States of America 3870 Email: caw@heapingbits.net 3872 Tommy Pauly 3873 Apple Inc. 3874 One Apple Park Way 3875 Cupertino, California 95014, 3876 United States of America 3878 Email: tpauly@apple.com 3880 Kyle Rose 3881 Akamai Technologies, Inc. 3882 145 Broadway 3883 Cambridge, MA, 3884 United States of America 3885 Email: krose@krose.org