idnits 2.17.1 draft-ietf-taps-interface-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 13 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Namespaces for each of the keywords provided in the IANA protocol numbers registry (see https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml), reformatted where necessary to conform to an implementation's naming conventions, are reserved for Protocol Specific Properties and MUST not be used for vendor or implementation-specific properties. -- The document date (July 27, 2020) is 1369 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) == Outdated reference: A later version (-19) exists of draft-ietf-taps-arch-08 ** Obsolete normative reference: RFC 4941 (Obsoleted by RFC 8981) ** Downref: Normative reference to an Informational RFC: RFC 8303 == Outdated reference: A later version (-18) exists of draft-ietf-taps-impl-07 -- Obsolete informational reference (is this intentional?): RFC 5245 (Obsoleted by RFC 8445, RFC 8839) -- Obsolete informational reference (is this intentional?): RFC 8229 (Obsoleted by RFC 9329) Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 3 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: January 28, 2021 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 TU Berlin 16 C. Wood 17 Cloudflare 18 T. Pauly 19 Apple Inc. 20 July 27, 2020 22 An Abstract Application Layer Interface to Transport Services 23 draft-ietf-taps-interface-09 25 Abstract 27 This document describes an abstract application programming 28 interface, API, to the transport layer, following the Transport 29 Services Architecture. It supports the asynchronous, atomic 30 transmission of messages over transport protocols and network paths 31 dynamically selected at runtime. It is intended to replace the 32 traditional BSD sockets API as the common interface to the transport 33 layer, in an environment where endpoints could select from multiple 34 interfaces and potential transport protocols. 36 Status of This Memo 38 This Internet-Draft is submitted in full conformance with the 39 provisions of BCP 78 and BCP 79. 41 Internet-Drafts are working documents of the Internet Engineering 42 Task Force (IETF). Note that other groups may also distribute 43 working documents as Internet-Drafts. The list of current Internet- 44 Drafts is at https://datatracker.ietf.org/drafts/current/. 46 Internet-Drafts are draft documents valid for a maximum of six months 47 and may be updated, replaced, or obsoleted by other documents at any 48 time. It is inappropriate to use Internet-Drafts as reference 49 material or to cite them other than as "work in progress." 51 This Internet-Draft will expire on January 28, 2021. 53 Copyright Notice 55 Copyright (c) 2020 IETF Trust and the persons identified as the 56 document authors. All rights reserved. 58 This document is subject to BCP 78 and the IETF Trust's Legal 59 Provisions Relating to IETF Documents 60 (https://trustee.ietf.org/license-info) in effect on the date of 61 publication of this document. Please review these documents 62 carefully, as they describe your rights and restrictions with respect 63 to this document. Code Components extracted from this document must 64 include Simplified BSD License text as described in Section 4.e of 65 the Trust Legal Provisions and are provided without warranty as 66 described in the Simplified BSD License. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 71 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 5 72 3. Overview of Interface Design . . . . . . . . . . . . . . . . 6 73 4. API Summary . . . . . . . . . . . . . . . . . . . . . . . . . 7 74 4.1. Usage Examples . . . . . . . . . . . . . . . . . . . . . 7 75 4.1.1. Server Example . . . . . . . . . . . . . . . . . . . 8 76 4.1.2. Client Example . . . . . . . . . . . . . . . . . . . 9 77 4.1.3. Peer Example . . . . . . . . . . . . . . . . . . . . 10 78 4.2. Transport Properties . . . . . . . . . . . . . . . . . . 11 79 4.2.1. Transport Property Names . . . . . . . . . . . . . . 12 80 4.2.2. Transport Property Types . . . . . . . . . . . . . . 13 81 4.3. Scope of the Interface Definition . . . . . . . . . . . . 14 82 5. Pre-Establishment Phase . . . . . . . . . . . . . . . . . . . 15 83 5.1. Specifying Endpoints . . . . . . . . . . . . . . . . . . 15 84 5.2. Specifying Transport Properties . . . . . . . . . . . . . 18 85 5.2.1. Reliable Data Transfer (Connection) . . . . . . . . . 20 86 5.2.2. Preservation of Message Boundaries . . . . . . . . . 20 87 5.2.3. Configure Per-Message Reliability . . . . . . . . . . 21 88 5.2.4. Preservation of Data Ordering . . . . . . . . . . . . 21 89 5.2.5. Use 0-RTT Session Establishment with a Safely 90 Replayable Message . . . . . . . . . . . . . . . . . 21 91 5.2.6. Multistream Connections in Group . . . . . . . . . . 22 92 5.2.7. Full Checksum Coverage on Sending . . . . . . . . . . 22 93 5.2.8. Full Checksum Coverage on Receiving . . . . . . . . . 22 94 5.2.9. Congestion control . . . . . . . . . . . . . . . . . 22 95 5.2.10. Interface Instance or Type . . . . . . . . . . . . . 23 96 5.2.11. Provisioning Domain Instance or Type . . . . . . . . 24 97 5.2.12. Use Temporary Local Address . . . . . . . . . . . . . 24 98 5.2.13. Multi-Paths Transport . . . . . . . . . . . . . . . . 25 99 5.2.14. Advertisement of Alternative Addresses . . . . . . . 26 100 5.2.15. Direction of communication . . . . . . . . . . . . . 26 101 5.2.16. Notification of excessive retransmissions . . . . . . 27 102 5.2.17. Notification of ICMP soft error message arrival . . . 27 103 5.2.18. Initiating side is not the first to write . . . . . . 27 104 5.3. Specifying Security Parameters and Callbacks . . . . . . 28 105 5.3.1. Pre-Connection Parameters . . . . . . . . . . . . . . 28 106 5.3.2. Connection Establishment Callbacks . . . . . . . . . 29 107 6. Establishing Connections . . . . . . . . . . . . . . . . . . 29 108 6.1. Active Open: Initiate . . . . . . . . . . . . . . . . . . 30 109 6.2. Passive Open: Listen . . . . . . . . . . . . . . . . . . 31 110 6.3. Peer-to-Peer Establishment: Rendezvous . . . . . . . . . 32 111 6.4. Connection Groups . . . . . . . . . . . . . . . . . . . . 33 112 7. Managing Connections . . . . . . . . . . . . . . . . . . . . 35 113 7.1. Generic Connection Properties . . . . . . . . . . . . . . 36 114 7.1.1. Retransmission Threshold Before Excessive 115 Retransmission Notification . . . . . . . . . . . . . 37 116 7.1.2. Required Minimum Corruption Protection Coverage for 117 Receiving . . . . . . . . . . . . . . . . . . . . . . 37 118 7.1.3. Priority (Connection) . . . . . . . . . . . . . . . . 37 119 7.1.4. Timeout for Aborting Connection . . . . . . . . . . . 37 120 7.1.5. Connection Group Transmission Scheduler . . . . . . . 38 121 7.1.6. Capacity Profile . . . . . . . . . . . . . . . . . . 38 122 7.1.7. Policy for using Multi-Path Transports . . . . . . . 40 123 7.1.8. Bounds on Send or Receive Rate . . . . . . . . . . . 40 124 7.1.9. Read-only Connection Properties . . . . . . . . . . . 41 125 7.2. TCP-specific Properties: User Timeout Option (UTO) . . . 42 126 7.2.1. Advertised User Timeout . . . . . . . . . . . . . . . 42 127 7.2.2. User Timeout Enabled . . . . . . . . . . . . . . . . 42 128 7.2.3. Timeout Changeable . . . . . . . . . . . . . . . . . 43 129 7.3. Connection Lifecycle Events . . . . . . . . . . . . . . . 43 130 7.3.1. Soft Errors . . . . . . . . . . . . . . . . . . . . . 43 131 7.3.2. Excessive retransmissions . . . . . . . . . . . . . . 43 132 8. Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . 43 133 8.1. Messages and Framers . . . . . . . . . . . . . . . . . . 43 134 8.1.1. Message Contexts . . . . . . . . . . . . . . . . . . 44 135 8.1.2. Message Framers . . . . . . . . . . . . . . . . . . . 44 136 8.1.3. Message Properties . . . . . . . . . . . . . . . . . 46 137 8.2. Sending Data . . . . . . . . . . . . . . . . . . . . . . 51 138 8.2.1. Basic Sending . . . . . . . . . . . . . . . . . . . . 52 139 8.2.2. Sending Replies . . . . . . . . . . . . . . . . . . . 52 140 8.2.3. Send Events . . . . . . . . . . . . . . . . . . . . . 52 141 8.2.4. Partial Sends . . . . . . . . . . . . . . . . . . . . 54 142 8.2.5. Batching Sends . . . . . . . . . . . . . . . . . . . 54 143 8.2.6. Send on Active Open: InitiateWithSend . . . . . . . . 55 145 8.3. Receiving Data . . . . . . . . . . . . . . . . . . . . . 55 146 8.3.1. Enqueuing Receives . . . . . . . . . . . . . . . . . 56 147 8.3.2. Receive Events . . . . . . . . . . . . . . . . . . . 56 148 8.3.3. Receive Message Properties . . . . . . . . . . . . . 58 149 9. Connection Termination . . . . . . . . . . . . . . . . . . . 59 150 10. Connection State and Ordering of Operations and Events . . . 60 151 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 61 152 12. Security Considerations . . . . . . . . . . . . . . . . . . . 61 153 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 63 154 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 63 155 14.1. Normative References . . . . . . . . . . . . . . . . . . 63 156 14.2. Informative References . . . . . . . . . . . . . . . . . 64 157 Appendix A. Convenience Functions . . . . . . . . . . . . . . . 67 158 A.1. Adding Preference Properties . . . . . . . . . . . . . . 67 159 A.2. Transport Property Profiles . . . . . . . . . . . . . . . 67 160 A.2.1. reliable-inorder-stream . . . . . . . . . . . . . . . 67 161 A.2.2. reliable-message . . . . . . . . . . . . . . . . . . 67 162 A.2.3. unreliable-datagram . . . . . . . . . . . . . . . . . 68 163 Appendix B. Relationship to the Minimal Set of Transport 164 Services for End Systems . . . . . . . . . . . . . . 68 165 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 72 167 1. Introduction 169 This document specifies a modern abstract application programming 170 interface (API) atop the high-level architecture for transport 171 services defined in [I-D.ietf-taps-arch]. It supports the 172 asynchronous, atomic transmission of messages over transport 173 protocols and network paths dynamically selected at runtime. It is 174 intended to replace the traditional BSD sockets API as the common 175 interface to the transport layer, in environments where endpoints 176 select from multiple interfaces and potential transport protocols. 178 As applications adopt this interface, they will benefit from a wide 179 set of transport features that can evolve over time, and ensure that 180 the system providing the interface can optimize its behavior based on 181 the application requirements and network conditions, without 182 requiring changes to the applications. This flexibility enables 183 faster deployment of new features and protocols. It can also support 184 applications by offering racing and fallback mechanisms, which 185 otherwise need to be separately implemented in each application. 187 It derives specific path and protocol selection properties and 188 supported transport features from the analysis provided in [RFC8095], 189 [I-D.ietf-taps-minset], and [I-D.ietf-taps-transport-security]. The 190 design encourages implementations underneath the interface to 191 dynamically choose a transport protocol depending on an application's 192 choices rather than statically binding applications to a protocol at 193 compile time. The transport system implementations should provide 194 applications with a way to override transport selection and 195 instantiate a specific stack, e.g., to support servers wishing to 196 listen to a specific protocol. This specific transport stack choice 197 is discouraged for general use, because it can reduce the 198 portability. 200 2. Terminology and Notation 202 This API is described in terms of Objects with which an application 203 can interact; Actions the application can perform on these Objects; 204 Events, which an Object can send to an application asynchronously; 205 and Parameters associated with these Actions and Events. 207 The following notations, which can be combined, are used in this 208 document: 210 o An Action creates an Object: 212 Object := Action() 214 o An Action creates an array of Objects: 216 []Object := Action() 218 o An Action is performed on an Object: 220 Object.Action() 222 o An Object sends an Event: 224 Object -> Event<> 226 o An Action takes a set of Parameters; an Event contains a set of 227 Parameters. Action and Event parameters whose names are suffixed 228 with a question mark are optional. 230 Action(param0, param1?, ...) / Event 232 Actions associated with no Object are Actions on the abstract 233 interface itself; they are equivalent to Actions on a per-application 234 global context. 236 The way these abstract concepts map into concrete implementations of 237 this API in a given language on a given platform largely depends on 238 the features of the language and the platform. Actions could be 239 implemented as functions or method calls, for instance, and Events 240 could be implemented via event queues, handler functions or classes, 241 communicating sequential processes, or other asynchronous calling 242 conventions. 244 This specification treats Events and errors similarly. Errors, just 245 as any other Events, may occur asynchronously in network 246 applications. However, it is recommended that implementations of 247 this interface also return errors immediately, according to the error 248 handling idioms of the implementation platform, for errors that can 249 be immediately detected, such as inconsistency in Transport 250 Properties. Errors can provide an optional reason to give the 251 application further details as to why the error occurred. 253 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 254 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 255 "OPTIONAL" in this document are to be interpreted as described in BCP 256 14 [RFC2119] [RFC8174] when, and only when, they appear in all 257 capitals, as shown here. 259 3. Overview of Interface Design 261 The design of the interface specified in this document is based on a 262 set of principles, themselves an elaboration on the architectural 263 design principles defined in [I-D.ietf-taps-arch]. The interface 264 defined in this document provides: 266 o A single interface to a variety of transport protocols to be used 267 in a variety of application design patterns, independent of the 268 properties of the application and the Protocol Stacks that will be 269 used at runtime, such that all common specialized features of 270 these protocol stacks are made available to the application as 271 necessary in a transport-independent way, to enable applications 272 written to a single API to make use of transport protocols in 273 terms of the features they provide; 275 o Message-orientation, as opposed to stream-orientation, using 276 application-assisted framing and deframing where the underlying 277 transport does not provide these; 279 o Asynchronous Connection establishment, transmission, and 280 reception, allowing concurrent operations during establishment and 281 supporting event-driven application interactions with the 282 transport layer, in line with developments in modern platforms and 283 programming languages; 285 o Explicit support for security properties as first-order transport 286 features, and for configuration of cryptographic identities and 287 transport security parameters persistent across multiple 288 Connections; and 290 o Explicit support for multistreaming and multipath transport 291 protocols, and the grouping of related Connections into Connection 292 Groups through cloning of Connections, to allow applications to 293 take full advantage of new transport protocols supporting these 294 features. 296 4. API Summary 298 The Transport Services API is the basic common abstract application 299 programming interface to the Transport Services Architecture defined 300 in the TAPS Architecture [I-D.ietf-taps-arch]. 302 An application primarily interacts with this API through two Objects: 303 Preconnections and Connections. A Preconnection represents a set of 304 properties and constraints on the selection and configuration of 305 paths and protocols to establish a Connection with a remote Endpoint. 306 A Connection represents a transport Protocol Stack on which data can 307 be sent to and/or received from a remote Endpoint (i.e., depending on 308 the kind of transport, connections can be bi-directional or 309 unidirectional). Connections can be created from Preconnections in 310 three ways: by initiating the Preconnection (i.e., actively opening, 311 as in a client), through listening on the Preconnection (i.e., 312 passively opening, as in a server), or rendezvousing on the 313 Preconnection (i.e. peer to peer establishment). 315 Once a Connection is established, data can be sent and received on it 316 in the form of Messages. The interface supports the preservation of 317 message boundaries both via explicit Protocol Stack support, and via 318 application support through a Message Framer which finds message 319 boundaries in a stream. Messages are received asynchronously through 320 event handlers registered by the application. Errors and other 321 notifications also happen asynchronously on the Connection. It is 322 not necessary for an application to handle all events; some events 323 may have implementation-specific default handlers. The application 324 should not assume that ignoring events (e.g. errors) is always safe. 326 Section 5, Section 6, Section 8.2, Section 8.3, and Section 9 327 describe the details of application interaction with Objects through 328 Actions and Events in each phase of a Connection, following the 329 phases (Pre-Establishment, Establishment, Data Transfer, and 330 Termination) described in Section 4.1 of [I-D.ietf-taps-arch]. 332 4.1. Usage Examples 334 The following usage examples illustrate how an application might use 335 a Transport Services Interface to: 337 o Act as a server, by listening for incoming connections, receiving 338 requests, and sending responses, see Section 4.1.1. 340 o Act as a client, by connecting to a remote endpoint using 341 Initiate, sending requests, and receiving responses, see 342 Section 4.1.2. 344 o Act as a peer, by connecting to a remote endpoint using Rendezvous 345 while simultaneously waiting for incoming Connections, sending 346 Messages, and receiving Messages, see Section 4.1.3. 348 The examples in this section presume that a transport protocol is 349 available between the endpoints that provides Reliable Data Transfer, 350 Preservation of data ordering, and Preservation of Message 351 Boundaries. In this case, the application can choose to receive only 352 complete messages. 354 If none of the available transport protocols provides Preservation of 355 Message Boundaries, but there is a transport protocol that provides a 356 reliable ordered byte stream, an application may receive this byte 357 stream as partial Messages and transform it into application-layer 358 Messages. Alternatively, an application may provide a Message 359 Framer, which can transform a byte stream into a sequence of Messages 360 (Section 8.1.2). 362 4.1.1. Server Example 364 This is an example of how an application might listen for incoming 365 Connections using the Transport Services Interface, receive a 366 request, and send a response. 368 LocalSpecifier := NewLocalEndpoint() 369 LocalSpecifier.WithInterface("any") 370 LocalSpecifier.WithService("https") 372 TransportProperties := NewTransportProperties() 373 TransportProperties.Require(preserve-msg-boundaries) 374 // Reliable Data Transfer and Preserve Order are Required by default 376 SecurityParameters := NewSecurityParameters() 377 SecurityParameters.AddIdentity(identity) 378 SecurityParameters.AddPrivateKey(privateKey, publicKey) 380 // Specifying a remote endpoint is optional when using Listen() 381 Preconnection := NewPreconnection(LocalSpecifier, 382 TransportProperties, 383 SecurityParameters) 385 Listener := Preconnection.Listen() 387 Listener -> ConnectionReceived 389 // Only receive complete messages in a Conn.Received handler 390 Connection.Receive() 392 Connection -> Received 394 //---- Receive event handler begin ---- 395 Connection.Send(messageDataResponse) 396 Connection.Close() 398 // Stop listening for incoming Connections 399 // (this example supports only one Connection) 400 Listener.Stop() 401 //---- Receive event handler end ---- 403 4.1.2. Client Example 405 This is an example of how an application might connect to a remote 406 application using the Transport Services Interface, send a request, 407 and receive a response. 409 RemoteSpecifier := NewRemoteEndpoint() 410 RemoteSpecifier.WithHostname("example.com") 411 RemoteSpecifier.WithService("https") 413 TransportProperties := NewTransportProperties() 414 TransportProperties.Require(preserve-msg-boundaries) 415 // Reliable Data Transfer and Preserve Order are Required by default 417 SecurityParameters := NewSecurityParameters() 418 TrustCallback := NewCallback({ 419 // Verify identity of the remote endpoint, return the result 420 }) 421 SecurityParameters.SetTrustVerificationCallback(TrustCallback) 423 // Specifying a local endpoint is optional when using Initiate() 424 Preconnection := NewPreconnection(RemoteSpecifier, 425 TransportProperties, 426 SecurityParameters) 428 Connection := Preconnection.Initiate() 430 Connection -> Ready<> 432 //---- Ready event handler begin ---- 433 Connection.Send(messageDataRequest) 435 // Only receive complete messages 436 Connection.Receive() 437 //---- Ready event handler end ---- 439 Connection -> Received 441 // Close the Connection in a Receive event handler 442 Connection.Close() 444 4.1.3. Peer Example 446 This is an example of how an application might establish a connection 447 with a peer using Rendezvous(), send a Message, and receive a 448 Message. 450 LocalSpecifier := NewLocalEndpoint() 451 LocalSpecifier.WithPort(9876) 453 RemoteSpecifier := NewRemoteEndpoint() 454 RemoteSpecifier.WithHostname("example.com") 455 RemoteSpecifier.WithPort(9877) 457 TransportProperties := NewTransportProperties() 458 TransportProperties.Require(preserve-msg-boundaries) 459 // Reliable Data Transfer and Preserve Order are Required by default 461 SecurityParameters := NewSecurityParameters() 462 SecurityParameters.AddIdentity(identity) 463 SecurityParameters.AddPrivateKey(privateKey, publicKey) 465 TrustCallback := New Callback({ 466 // Verify identity of the remote endpoint, return the result 467 }) 468 SecurityParameters.SetTrustVerificationCallback(trustCallback) 470 // Both local and remote endpoint must be specified 471 Preconnection := NewPreconnection(LocalSpecifier, 472 RemoteSpecifier, 473 TransportProperties, 474 SecurityParameters) 476 Preconnection.Rendezvous() 478 Preconnection -> RendezvousDone 480 //---- Ready event handler begin ---- 481 Connection.Send(messageDataRequest) 483 // Only receive complete messages 484 Connection.Receive() 485 //---- Ready event handler end ---- 487 Connection -> Received 489 // Close the Connection in a Receive event handler 490 Connection.Close() 492 4.2. Transport Properties 494 Each application using the Transport Services Interface declares its 495 preferences for how the transport service should operate using 496 properties at each stage of the lifetime of a connection using 497 Transport Properties, as defined in [I-D.ietf-taps-arch]. 499 Transport Properties are divided into Selection, Connection, and 500 Message Properties. Selection Properties (see Section 5.2) can only 501 be set during pre-establishment. They are only used to specify which 502 paths and protocol stacks can be used and are preferred by the 503 application. Connection Properties (see Section 7.1) can also be set 504 during pre-establishment but may be changed later. They are used to 505 inform decisions made during establishment and to fine-tune the 506 established connection. 507 The behavior of the selected protocol stack(s) when sending Messages 508 is controlled by Message Properties (see Section 8.1.3). 510 All Transport Properties, regardless of the phase in which they are 511 used, are organized within a single namespace. This enables setting 512 them as defaults in earlier stages and querying them in later stages: 514 o Connection Properties can be set on Preconnections 516 o Message Properties can be set on Preconnections, Connections and 517 Messages 519 o The effect of Selection Properties can be queried on Connections 520 and Messages 522 Note that configuring Connection Properties and Message Properties on 523 Preconnections is preferred over setting them later. Early 524 specification of Connection Properties allows their use as additional 525 input to the selection process. Protocol Specific Properties, which 526 enable configuration of specialized features of a specific protocol, 527 see Section 3.2 of [I-D.ietf-taps-arch], are not used as an input to 528 the selection process but only support configuration if the 529 respective protocol has been selected. 531 4.2.1. Transport Property Names 533 Transport Properties are referred to by property names. For the 534 purposes of this document, these names are alphanumeric strings in 535 which words may be separated by hyphens. These names serve two 536 purposes: 538 o Allowing different components of a TAPS implementation to pass 539 Transport Properties, e.g., between a language frontend and a 540 policy manager, or as a representation of properties retrieved 541 from a file or other storage. 543 o Making code of different TAPS implementations look similar. While 544 individual programming languages may preclude strict adherence to 545 the aforementioned naming convention (for instance, by prohibiting 546 the use of hyphens in symbols), users interacting with multiple 547 implementations will still benefit from the consistency resulting 548 from the use of visually similar symbols. 550 Transport Property Names are hierarchically organized in the form 551 [.]. 553 o The Namespace component MUST be empty for well-known, generic 554 properties, i.e., for properties that are not specific to a 555 protocol and are defined in an RFC. 557 o Protocol Specific Properties MUST use the protocol acronym as 558 Namespace, e.g., "tcp" for TCP specific Transport Properties. For 559 IETF protocols, property names under these namespaces SHOULD be 560 defined in an RFC. 562 o Vendor or implementation specific properties MUST use a string 563 identifying the vendor or implementation as Namespace. 565 Namespaces for each of the keywords provided in the IANA protocol 566 numbers registry (see https://www.iana.org/assignments/protocol- 567 numbers/protocol-numbers.xhtml), reformatted where necessary to 568 conform to an implementation's naming conventions, are reserved for 569 Protocol Specific Properties and MUST not be used for vendor or 570 implementation-specific properties. 572 4.2.2. Transport Property Types 574 Transport Properties can have one of a set of data types: 576 o Boolean: can take the values "true" and "false"; representation is 577 implementation-dependent. 579 o Integer: can take positive or negative numeric integer values; 580 range and representation is implementation-dependent. 582 o Numeric: can take positive or negative numeric values; range and 583 representation is implementation-dependent. 585 o Enumeration: can take one value of a finite set of values, 586 dependent on the property itself. The representation is 587 implementation dependent; however, implementations MUST provide a 588 method for the application to determine the entire set of possible 589 values for each property. 591 o Preference: can take one of five values (Prohibit, Avoid, Ignore, 592 Prefer, Require) for the level of preference of a given property 593 during protocol selection; see Section 5.2. When querying, a 594 Preference is of type Boolean, with "true" indicating that the 595 Selection Property has been applied. 597 For types Integer and Numeric, special values can be defined per 598 property; it is up to implementations how these special values are 599 represented (e.g., by using -1 for an otherwise non-negative value). 601 4.3. Scope of the Interface Definition 603 This document defines a language- and platform-independent interface 604 to a Transport Services system. Given the wide variety of languages 605 and language conventions used to write applications that use the 606 transport layer to connect to other applications over the Internet, 607 this independence makes this interface necessarily abstract. 609 There is no interoperability benefit in tightly defining how the 610 interface is presented to application programmers across diverse 611 platforms. However, maintaining the "shape" of the abstract 612 interface across these platforms reduces the effort for programmers 613 who learn the transport services interface to then apply their 614 knowledge across multiple platforms. 616 We therefore make the following recommendations: 618 o Actions, Events, and Errors in implementations of this interface 619 SHOULD use the names given for them in the document, subject to 620 capitalization, punctuation, and other typographic conventions in 621 the language of the implementation, unless the implementation 622 itself uses different names for substantially equivalent objects 623 for networking by convention. 625 o Implementations of this interface SHOULD implement each Selection 626 Property, Connection Property, and Message Context Property 627 specified in this document. Each interface SHOULD be implemented 628 even when this will always result in no operation, e.g. there is 629 no action when the API specifies a Property that is not available 630 in a transport protocol implemented on a specific platform. For 631 example, if TCP is the only underlying transport protocol, the 632 Message Property "msgOrdered" can be implemented even if disabling 633 ordering will not have any effect TCP because the API does not 634 guarantee out-of-order delivery. Similarly, the "msg-lifetime" 635 Message Property can be implemented but ignored, as the 636 description of this Property states that "it is not guaranteed 637 that a Message will not be sent when its Lifetime has expired". 639 o Implementations may use other representations for Transport 640 Property Names, e.g., by providing constants, but should provide a 641 straight-forward mapping between their representation and the 642 property names specified here. 644 5. Pre-Establishment Phase 646 The Pre-Establishment phase allows applications to specify properties 647 for the Connections they are about to make, or to query the API about 648 potential Connections they could make. 650 A Preconnection Object represents a potential Connection. It has 651 state that describes properties of a Connection that might exist in 652 the future. This state comprises Local Endpoint and Remote Endpoint 653 Objects that denote the endpoints of the potential Connection (see 654 Section 5.1), the Selection Properties (see Section 5.2), any 655 preconfigured Connection Properties (Section 7.1), and the security 656 parameters (see Section 5.3): 658 Preconnection := NewPreconnection(LocalEndpoint?, 659 RemoteEndpoint?, 660 TransportProperties, 661 SecurityParams) 663 The Local Endpoint MUST be specified if the Preconnection is used to 664 Listen() for incoming Connections, but is OPTIONAL if it is used to 665 Initiate() connections. If no Local Endpoint is specified, the 666 Transport System will assign an ephemeral local port to the 667 Connection. The Remote Endpoint MUST be specified if the 668 Preconnection is used to Initiate() Connections, but is OPTIONAL if 669 it is used to Listen() for incoming Connections. The Local Endpoint 670 and the Remote Endpoint MUST both be specified if a peer-to-peer 671 Rendezvous is to occur based on the Preconnection. 673 Transport Properties MUST always be specified while security 674 parameters are OPTIONAL. 676 If Message Framers are used (see Section 8.1.2), they MUST be added 677 to the Preconnection during pre-establishment. 679 5.1. Specifying Endpoints 681 The transport services API uses the Local Endpoint and Remote 682 Endpoint Objects to refer to the endpoints of a transport connection. 683 Actions on these Objects can be used to represent various different 684 types of endpoint identifiers, such as IP addresses, DNS names, and 685 interface names, as well as port numbers and service names. 687 Specify a Remote Endpoint using a hostname and service name: 689 RemoteSpecifier := NewRemoteEndpoint() 690 RemoteSpecifier.WithHostname("example.com") 691 RemoteSpecifier.WithService("https") 693 Specify a Remote Endpoint using an IPv6 address and remote port: 695 RemoteSpecifier := NewRemoteEndpoint() 696 RemoteSpecifier.WithIPv6Address(2001:db8:4920:e29d:a420:7461:7073:0a) 697 RemoteSpecifier.WithPort(443) 699 Specify a Remote Endpoint using an IPv4 address and remote port: 701 RemoteSpecifier := NewRemoteEndpoint() 702 RemoteSpecifier.WithIPv4Address(192.0.2.21) 703 RemoteSpecifier.WithPort(443) 705 Specify a Local Endpoint using a local interface name and local port: 707 LocalSpecifier := NewLocalEndpoint() 708 LocalSpecifier.WithInterface("en0") 709 LocalSpecifier.WithPort(443) 711 As an alternative to specifying an interface name for the Local 712 Endpoint, an application can express more fine-grained preferences 713 using the "Interface Instance or Type" Selection Property, see 714 Section 5.2.10. However, if the application specifies Selection 715 Properties which are inconsistent with the Local Endpoint, this will 716 result in an error once the application attempts to open a 717 Connection. 719 Specify a Local Endpoint using a STUN server: 721 LocalSpecifier := NewLocalEndpoint() 722 LocalSpecifier.WithStunServer(address, port, credentials) 724 Specify a Local Endpoint using a Any-Source Multicast group to join 725 on a named local interface: 727 LocalSpecifier := NewLocalEndpoint() 728 LocalSpecifier.WithIPv4Address(233.252.0.0) 729 LocalSpecifier.WithInterface("en0") 731 Source-Specific Multicast requires setting both a Local and Remote 732 Endpoint: 734 LocalSpecifier := NewLocalEndpoint() 735 LocalSpecifier.WithIPv4Address(232.1.1.1) 736 LocalSpecifier.WithInterface("en0") 738 RemoteSpecifier := NewRemoteEndpoint() 739 RemoteSpecifier.WithIPv4Address(192.0.2.22) 741 Implementations may also support additional endpoint representations 742 and provide a single NewEndpoint() call that takes different endpoint 743 representations. 745 Multiple endpoint identifiers can be specified for each Local 746 Endpoint and Remote Endpoint. For example, a Local Endpoint could be 747 configured with two interface names, or a Remote Endpoint could be 748 specified via both IPv4 and IPv6 addresses. These multiple 749 identifiers refer to the same transport endpoint. 751 The transport services API resolves names internally, when the 752 Initiate(), Listen(), or Rendezvous() method is called to establish a 753 Connection. The API explicitly does not require the application to 754 resolve names, though there is a tradeoff between early and late 755 binding of addresses to names. Early binding allows the API 756 implementation to reduce connection setup latency, at the cost of 757 potentially limited scope for alternate path discovery during 758 Connection establishment, as well as potential additional information 759 leakage about application interest when used with a resolution method 760 (such as DNS without TLS) which does not protect query 761 confidentiality. 763 The Resolve() action on Preconnection can be used by the application 764 to force early binding when required, for example with some Network 765 Address Translator (NAT) traversal protocols (see Section 6.3). 767 Specifying a multicast group address on the Local Endpoint will 768 indicate to the transport system that the resulting connection will 769 be used to receive multicast messages. The Remote Endpoint can be 770 used to filter by specific senders. This will restrict the 771 application to establishing the Preconnection by calling Listen(). 772 The accepted Connections are receive-only. 774 Similarly, specifying a multicast group address on the Remote 775 Endpoint will indicate that the resulting connection will be used to 776 send multicast messages. 778 5.2. Specifying Transport Properties 780 A Preconnection Object holds properties reflecting the application's 781 requirements and preferences for the transport. These include 782 Selection Properties for selecting protocol stacks and paths, as well 783 as Connection Properties for configuration of the detailed operation 784 of the selected Protocol Stacks. 786 The protocol(s) and path(s) selected as candidates during 787 establishment are determined and configured using these properties. 788 Since there could be paths over which some transport protocols are 789 unable to operate, or remote endpoints that support only specific 790 network addresses or transports, transport protocol selection is 791 necessarily tied to path selection. This may involve choosing 792 between multiple local interfaces that are connected to different 793 access networks. 795 Most Selection Properties are represented as preferences, which can 796 have one of five preference levels: 798 +------------+------------------------------------------------------+ 799 | Preference | Effect | 800 +------------+------------------------------------------------------+ 801 | Require | Select only protocols/paths providing the property, | 802 | | fail otherwise | 803 | | | 804 | Prefer | Prefer protocols/paths providing the property, | 805 | | proceed otherwise | 806 | | | 807 | Ignore | No preference | 808 | | | 809 | Avoid | Prefer protocols/paths not providing the property, | 810 | | proceed otherwise | 811 | | | 812 | Prohibit | Select only protocols/paths not providing the | 813 | | property, fail otherwise | 814 +------------+------------------------------------------------------+ 816 In addition, the pseudo-level "Default" can be used to reset the 817 property to the default level used by the implementation. This level 818 will never show up when queuing the value of a preference - the 819 effective preference must be returned instead. 821 The implementation MUST ensure an outcome that is consistent with 822 application requirements as expressed using Require and Prohibit. 823 While preferences expressed using Prefer and Avoid influence protocol 824 and path selection as well, outcomes may vary given the same 825 Selection Properties, as the available protocols and paths may vary 826 across systems and contexts. However, implementations are 827 RECOMMENDED to aim to provide a consistent outcome to an application, 828 given the same Selection Properties. 830 Note that application preferences may conflict with each other. For 831 example, if an application indicates a preference for a specific path 832 by specifying an interface, but also a preference for a protocol, a 833 situation might occur in which the preferred protocol is not 834 available on the preferred path. In such cases, implementations 835 SHOULD prioritize Selection Properties that select paths over those 836 that select protocols. Therefore, the transport system SHOULD race 837 the path first, ignoring the protocol preference if the protocol does 838 not work on the path. 840 Selection and Connection Properties, as well as defaults for Message 841 Properties, can be added to a Preconnection to configure the 842 selection process and to further configure the eventually selected 843 protocol stack(s). They are collected into a TransportProperties 844 object to be passed into a Preconnection object: 846 TransportProperties := NewTransportProperties() 848 Individual properties are then added to the TransportProperties 849 Object: 851 TransportProperties.Add(property, value) 853 Selection Properties of type "Preference" can be frequently used. 854 Implementations MAY therefore provide additional convenience 855 functions, see Appendix A.1 for examples. In addition, 856 implementations MAY provide a mechanism to create TransportProperties 857 objects that are preconfigured for common use cases as outlined in 858 Appendix A.2. 860 For an existing Connection, the Transport Properties can be queried 861 any time by using the following call on the Connection Object: 863 TransportProperties := Connection.GetTransportProperties() 865 A Connection gets its Transport Properties either by being explicitly 866 configured via a Preconnection, by configuration after establishment, 867 or by inheriting them from an antecedent via cloning; see Section 6.4 868 for more. 870 Section 7.1 provides a list of Connection Properties, while Selection 871 Properties are listed in the subsections below. Note that many 872 properties are only considered during establishment, and can not be 873 changed after a Connection is established; however, they can be 874 queried. The return type of a queried Selection Property is Boolean, 875 where "true" means that the Selection Property has been applied and 876 "false" means that the Selection Property has not been applied. Note 877 that "true" does not mean that a request has been honored. For 878 example, if "Congestion control" was requested with preference level 879 "Prefer", but congestion control could not be supported, querying the 880 "congestionControl" property yields the value "false". If preference 881 level "Avoid" was used for "Congestion control", and, as requested, 882 the Connection is not congestion controlled, querying the 883 "congestionControl" property also yields the value "false". 885 An implementation of this interface must provide sensible defaults 886 for Selection Properties. The recommended default values for each 887 property below represent a configuration that can be implemented over 888 TCP. If these default values are used and TCP is not supported by a 889 Transport Services implementation, then an application using the 890 default set of Properties might not succeed in establishing a 891 connection. Using the same default values for independent Transport 892 Services implementations can be beneficical when application are 893 ported between different implementations, even if this default could 894 lead to a connection failure, as, for example, an application needs 895 to be explicitly designed to support a connectionless mode. In this 896 case the application can regonize the failure and explicitly specify 897 a different set of Protocol Selection Properties that result in a 898 usable protocol. If default values other than those recommended 899 below are used, it is recommended to clearly document the 900 differences. 902 5.2.1. Reliable Data Transfer (Connection) 904 Name: reliability 906 Type: Preference 908 Default: Require 910 This property specifies whether the application needs to use a 911 transport protocol that ensures that all data is received on the 912 other side without corruption. This also entails being notified when 913 a Connection is closed or aborted when reliable data transfer is 914 enabled. 916 5.2.2. Preservation of Message Boundaries 918 Name: preserveMsgBoundaries 920 Type: Preference 921 Default: Prefer 923 This property specifies whether the application needs or prefers to 924 use a transport protocol that preserves message boundaries. 926 5.2.3. Configure Per-Message Reliability 928 Name: perMsgReliability 930 Type: Preference 932 Default: Ignore 934 This property specifies whether an application considers it useful to 935 indicate its reliability requirements on a per-Message basis. This 936 property applies to Connections and Connection Groups. 938 5.2.4. Preservation of Data Ordering 940 Name: preserveOrder 942 Type: Preference 944 Default: Require 946 This property specifies whether the application wishes to use a 947 transport protocol that can ensure that data is received by the 948 application on the other end in the same order as it was sent. 950 5.2.5. Use 0-RTT Session Establishment with a Safely Replayable Message 952 Name: zeroRttMsg 954 Type: Preference 956 Default: Ignore 958 This property specifies whether an application would like to supply a 959 Message to the transport protocol before Connection establishment, 960 which will then be reliably transferred to the other side before or 961 during Connection establishment, potentially multiple times (i.e., 962 multiple copies of the message data may be passed to the Remote 963 Endpoint). See also Section 8.1.3.4. Note that disabling this 964 property has no effect for protocols that are not connection-oriented 965 and do not protect against duplicated messages, e.g., UDP. 967 5.2.6. Multistream Connections in Group 969 Name: multistreaming 971 Type: Preference 973 Default: Prefer 975 This property specifies that the application would prefer multiple 976 Connections within a Connection Group to be provided by streams of a 977 single underlying transport connection where possible. 979 5.2.7. Full Checksum Coverage on Sending 981 Name: perMsgChecksumLenSend 983 Type: Preference 985 Default: Require 987 This property specifies whether the application desires protection 988 against corruption for all data transmitted on this Connection. 989 Disabling this property may enable to control checksum coverage later 990 (see Section 8.1.3.6). 992 5.2.8. Full Checksum Coverage on Receiving 994 Name: perMsgChecksumLenRecv 996 Type: Preference 998 Default: Require 1000 This property specifies whether the application desires protection 1001 against corruption for all data received on this Connection. 1003 5.2.9. Congestion control 1005 Name: congestionControl 1007 Type: Preference 1009 Default: Require 1011 This property specifies whether the application would like the 1012 Connection to be congestion controlled or not. Note that if a 1013 Connection is not congestion controlled, an application using such a 1014 Connection should itself perform congestion control in accordance 1015 with [RFC2914]. Also note that reliability is usually combined with 1016 congestion control in protocol implementations, rendering "reliable 1017 but not congestion controlled" a request that is unlikely to succeed. 1019 5.2.10. Interface Instance or Type 1021 Name: interface 1023 Type: Set (Preference, Enumeration) 1025 Default: Empty set (not setting a preference for any interface) 1027 This property allows the application to select which specific network 1028 interfaces or categories of interfaces it wants to "Require", 1029 "Prohibit", "Prefer", or "Avoid". Note that marking a specific 1030 interface as "Require" strictly limits path selection to a single 1031 interface, and may often lead to less flexible and resilient 1032 connection establishment. 1034 In contrast to other Selection Properties, this property is a tuple 1035 of an (Enumerated) interface identifier and a preference, and can 1036 either be implemented directly as such, or for making one preference 1037 available for each interface and interface type available on the 1038 system. 1040 The set of valid interface types is implementation- and system- 1041 specific. For example, on a mobile device, there may be "Wi-Fi" and 1042 "Cellular" interface types available; whereas on a desktop computer, 1043 there may be "Wi-Fi" and "Wired Ethernet" interface types available. 1044 An implementation should provide all types that are supported on the 1045 local system to all remote systems, to allow applications to be 1046 written generically. For example, if a single implementation is used 1047 on both mobile devices and desktop devices, it should define the 1048 "Cellular" interface type for both systems, since an application may 1049 want to always "Prohibit Cellular". 1051 The set of interface types is expected to change over time as new 1052 access technologies become available. The taxonomy of interface 1053 types on a given Transport Services system is implementation- 1054 specific. 1056 Interface types should not be treated as a proxy for properties of 1057 interfaces such as metered or unmetered network access. If an 1058 application needs to prohibit metered interfaces, this should be 1059 specified via Provisioning Domain attributes (see Section 5.2.11) or 1060 another specific property. 1062 5.2.11. Provisioning Domain Instance or Type 1064 Name: pvd 1066 Type: Set (Preference, Enumeration) 1068 Default: Empty set (not setting a preference for any PvD) 1070 Similar to interface instances and types (see Section 5.2.10), this 1071 property allows the application to control path selection by 1072 selecting which specific Provisioning Domains or categories of 1073 Provisioning Domains it wants to "Require", "Prohibit", "Prefer", or 1074 "Avoid". Provisioning Domains define consistent sets of network 1075 properties that may be more specific than network interfaces 1076 [RFC7556]. 1078 As with interface instances and types, this property is a tuple of an 1079 (Enumerated) PvD identifier and a preference, and can either be 1080 implemented directly as such, or for making one preference available 1081 for each interface and interface type available on the system. 1083 The identification of a specific Provisioning Domain (PvD) is defined 1084 to be implementation- and system-specific, since there is not a 1085 portable standard format for a PvD identifier. For example, this 1086 identifier may be a string name or an integer. As with requiring 1087 specific interfaces, requiring a specific PvD strictly limits path 1088 selection. 1090 Categories or types of PvDs are also defined to be implementation- 1091 and system-specific. These may be useful to identify a service that 1092 is provided by a PvD. For example, if an application wants to use a 1093 PvD that provides a Voice-Over-IP service on a Cellular network, it 1094 can use the relevant PvD type to require some PvD that provides this 1095 service, without needing to look up a particular instance. While 1096 this does restrict path selection, it is broader than requiring 1097 specific PvD instances or interface instances, and should be 1098 preferred over these options. 1100 5.2.12. Use Temporary Local Address 1102 Name: useTemporaryLocalAddress 1104 Type: Preference 1106 Default: Avoid for Listeners and Rendezvous Connections. Prefer for 1107 other Connections. 1109 This property allows the application to express a preference for the 1110 use of temporary local addresses, sometimes called "privacy" 1111 addresses [RFC4941]. Temporary addresses are generally used to 1112 prevent linking connections over time when a stable address, 1113 sometimes called "permanent" address, is not needed. Note that if an 1114 application Requires the use of temporary addresses, the resulting 1115 Connection cannot use IPv4, as temporary addresses do not exist in 1116 IPv4. 1118 5.2.13. Multi-Paths Transport 1120 Name: multipath 1122 Type: Enumeration 1124 Default: Disabled for connections created through initiate and 1125 rendezvous, Passive for listeners 1127 This property specifies whether and how applications want to take 1128 advantage of transferring data across multiple paths between the same 1129 end hosts. Using multiple paths allows connections to migrate 1130 between interfaces or aggregate bandwidth as availability and 1131 performance properties change. Possible values are: 1133 Disabled: The connection will not use multiple paths once 1134 established, even if the chosen transport supports using multiple 1135 paths. 1137 Active: The connection will negotiate the use of multiple paths if 1138 the chosen transport supports this. 1140 Passive: The connection will support the use of multiple paths if 1141 the remote endpoint requests it. 1143 The policy for using multiple paths is specified using the separate 1144 "multipath-policy" property, see Section 7.1.7 below. To enable the 1145 peer endpoint to initiate additional paths towards a local address 1146 other than the one initially used, it is necessary to set the 1147 Alternative Addresses property (see Section 5.2.14 below). 1149 Setting this property to "Active", may have privacy implications: It 1150 enables the transport to establish connectivity using alternate paths 1151 that may make users linkable across multiple paths, even if the 1152 Advertisement of Alternative Addresses property (see Section 5.2.14 1153 below) is set to false. 1155 Enumeration values other than "Disabled" are interpreted as a 1156 preference for choosing protocols that can make use of multiple 1157 paths. The "Disabled" value implies a requirement not to use 1158 multiple paths in parallel but does not prevent choosing a protocol 1159 that is capable of using multiple paths, e.g., it does not prevent 1160 choosing TCP, but prevents sending the "MP_CAPABLE" option in the TCP 1161 handshake. 1163 5.2.14. Advertisement of Alternative Addresses 1165 Name: advertises-altaddr 1167 Type: Boolean 1169 Default: False 1171 This property specifies whether alternative addresses, e.g., of other 1172 interfaces, should be advertised to the peer endpoint by the protocol 1173 stack. Advertising these addresses enables the peer-endpoint to 1174 establish additional connectivity, e.g., for connection migration or 1175 using multiple paths. 1177 Note that this may have privacy implications because it may make 1178 users linkable across multiple paths. Also, note that setting this 1179 to false does not prevent the local transport system from 1180 _establishing_ connectivity using alternate paths (see Section 5.2.13 1181 above); it only prevents _procative advertisement_ of addresses. 1183 5.2.15. Direction of communication 1185 Name: direction 1187 Type: Enumeration 1189 Default: Bidirectional 1191 This property specifies whether an application wants to use the 1192 connection for sending and/or receiving data. Possible values are: 1194 Bidirectional: The connection must support sending and receiving 1195 data 1197 Unidirectional send: The connection must support sending data, and 1198 the application cannot use the connection to receive any data 1200 Unidirectional receive: The connection must support receiving data, 1201 and the application cannot use the connection to send any data 1203 Since unidirectional communication can be supported by transports 1204 offering bidirectional communication, specifying unidirectional 1205 communication may cause a transport stack that supports bidirectional 1206 communication to be selected. 1208 5.2.16. Notification of excessive retransmissions 1210 Name: retransmitNotify 1212 Type: Preference 1214 Default: Ignore 1216 This property specifies whether an application considers it useful to 1217 be informed in case sent data was retransmitted more often than a 1218 certain threshold (see Section 7.1.1 for configuration of this 1219 threshold). 1221 5.2.17. Notification of ICMP soft error message arrival 1223 Name: softErrorNotify 1225 Type: Preference 1227 Default: Ignore 1229 This property specifies whether an application considers it useful to 1230 be informed when an ICMP error message arrives that does not force 1231 termination of a connection. When set to true, received ICMP errors 1232 will be available as SoftErrors, see Section 7.3.1. Note that even 1233 if a protocol supporting this property is selected, not all ICMP 1234 errors will necessarily be delivered, so applications cannot rely on 1235 receiving them. 1237 5.2.18. Initiating side is not the first to write 1239 Name: activeReadBeforeSend 1241 Type: Preference 1243 Default: Ignore 1245 The most common client-server communication pattern involves the 1246 client actively opening a connection, then sending data to the 1247 server. The server listens (passive open), reads, and then answers. 1248 This property specifies whether an application wants to diverge from 1249 this pattern - either by actively opening with Initiate(), 1250 immediately followed by reading, or passively opening with Listen(), 1251 immediately followed by writing. This property is ignored when 1252 establishing connections using Rendezvous(). Requiring this property 1253 limits the choice of mappings to underlying protocols, which can 1254 reduce efficiency. For example, it prevents the transport system 1255 from mapping Connections to SCTP streams, where the first transmitted 1256 data takes the role of an active open signal [I-D.ietf-taps-impl]. 1258 5.3. Specifying Security Parameters and Callbacks 1260 Most security parameters, e.g., TLS ciphersuites, local identity and 1261 private key, etc., may be configured statically. Others are 1262 dynamically configured during connection establishment. Thus, we 1263 partition security parameters and callbacks based on their place in 1264 the lifetime of connection establishment. Similar to Transport 1265 Properties, both parameters and callbacks are inherited during 1266 cloning (see Section 6.4). 1268 5.3.1. Pre-Connection Parameters 1270 Common parameters such as TLS ciphersuites are known to 1271 implementations. Clients should use common safe defaults for these 1272 values whenever possible. However, as discussed in 1273 [I-D.ietf-taps-transport-security], many transport security protocols 1274 require specific security parameters and constraints from the client 1275 at the time of configuration and actively during a handshake. These 1276 configuration parameters need to be specified in the pre-connection 1277 phase and are created as follows: 1279 SecurityParameters := NewSecurityParameters() 1281 Security configuration parameters and sample usage follow: 1283 o Local identity and private keys: Used to perform private key 1284 operations and prove one's identity to the Remote Endpoint. 1285 (Note, if private keys are not available, e.g., since they are 1286 stored in hardware security modules (HSMs), handshake callbacks 1287 must be used. See below for details.) 1289 SecurityParameters.Add('identity', identity) 1290 SecurityParameters.Add('keypair', privateKey, publicKey) 1292 o Supported algorithms: Used to restrict what parameters are used by 1293 underlying transport security protocols. When not specified, 1294 these algorithms should use known and safe defaults for the 1295 system. Parameters include: ciphersuites, supported groups, and 1296 signature algorithms. 1298 SecurityParameters.Add('supported-group', 'secp256k1') 1299 SecurityParameters.Add('ciphersuite, 'TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256') 1300 SecurityParameters.Add('signature-algorithm', 'ed25519') 1301 o Pre-Shared Key import: Used to install pre-shared keying material 1302 established out-of-band. Each pre-shared keying material is 1303 associated with some identity that typically identifies its use or 1304 has some protocol-specific meaning to the Remote Endpoint. 1306 SecurityParameters.Add('pre-shared-key', key, identity) 1308 o Session cache management: Used to tune cache capacity, lifetime, 1309 re-use, and eviction policies, e.g., LRU or FIFO.may also me 1310 changed, but are implementation-specific. 1312 5.3.2. Connection Establishment Callbacks 1314 Security decisions, especially pertaining to trust, are not static. 1315 Once configured, parameters may also be supplied during connection 1316 establishment. These are best handled as client-provided callbacks. 1317 Security handshake callbacks that may be invoked during connection 1318 establishment include: 1320 o Trust verification callback: Invoked when a Remote Endpoint's 1321 trust must be validated before the handshake protocol can 1322 continue. 1324 TrustCallback := NewCallback({ 1325 // Handle trust, return the result 1326 }) 1327 SecurityParameters.SetTrustVerificationCallback(trustCallback) 1329 o Identity challenge callback: Invoked when a private key operation 1330 is required, e.g., when local authentication is requested by a 1331 remote. 1333 ChallengeCallback := NewCallback({ 1334 // Handle challenge 1335 }) 1336 SecurityParameters.SetIdentityChallengeCallback(challengeCallback) 1338 6. Establishing Connections 1340 Before a Connection can be used for data transfer, it must be 1341 established. Establishment ends the pre-establishment phase; all 1342 transport properties and cryptographic parameter specification must 1343 be complete before establishment, as these will be used to select 1344 candidate Paths and Protocol Stacks for the Connection. 1345 Establishment may be active, using the Initiate() Action; passive, 1346 using the Listen() Action; or simultaneous for peer-to-peer, using 1347 the Rendezvous() Action. These Actions are described in the 1348 subsections below. 1350 6.1. Active Open: Initiate 1352 Active open is the Action of establishing a Connection to a Remote 1353 Endpoint presumed to be listening for incoming Connection requests. 1354 Active open is used by clients in client-server interactions. Active 1355 open is supported by this interface through the Initiate Action: 1357 Connection := Preconnection.Initiate(timeout?) 1359 The timeout parameter specifies how long to wait before aborting 1360 Active open. Before calling Initiate, the caller must have populated 1361 a Preconnection Object with a Remote Endpoint specifier, optionally a 1362 Local Endpoint specifier (if not specified, the system will attempt 1363 to determine a suitable Local Endpoint), as well as all properties 1364 necessary for candidate selection. 1366 The Initiate() Action returns a Connection object. Once Initiate() 1367 has been called, any changes to the Preconnection MUST NOT have any 1368 effect on the Connection. However, the Preconnection can be reused, 1369 e.g., to Initiate another Connection. 1371 Once Initiate is called, the candidate Protocol Stack(s) may cause 1372 one or more candidate transport-layer connections to be created to 1373 the specified remote endpoint. The caller may immediately begin 1374 sending Messages on the Connection (see Section 8.2) after calling 1375 Initiate(); note that any data marked "Safely Replayable" that is 1376 sent while the Connection is being established may be sent multiple 1377 times or on multiple candidates. 1379 The following Events may be sent by the Connection after Initiate() 1380 is called: 1382 Connection -> Ready<> 1384 The Ready Event occurs after Initiate has established a transport- 1385 layer connection on at least one usable candidate Protocol Stack over 1386 at least one candidate Path. No Receive Events (see Section 8.3) 1387 will occur before the Ready Event for Connections established using 1388 Initiate. 1390 Connection -> EstablishmentError 1392 An EstablishmentError occurs either when the set of transport 1393 properties and security parameters cannot be fulfilled on a 1394 Connection for initiation (e.g. the set of available Paths and/or 1395 Protocol Stacks meeting the constraints is empty) or reconciled with 1396 the local and/or remote Endpoints; when the remote specifier cannot 1397 be resolved; or when no transport-layer connection can be established 1398 to the remote Endpoint (e.g. because the remote Endpoint is not 1399 accepting connections, the application is prohibited from opening a 1400 Connection by the operating system, or the establishment attempt has 1401 timed out for any other reason). 1403 See also Section 8.2.6 to combine Connection establishment and 1404 transmission of the first message in a single action. 1406 6.2. Passive Open: Listen 1408 Passive open is the Action of waiting for Connections from remote 1409 Endpoints, commonly used by servers in client-server interactions. 1410 Passive open is supported by this interface through the Listen Action 1411 and returns a Listener object: 1413 Listener := Preconnection.Listen() 1415 Before calling Listen, the caller must have initialized the 1416 Preconnection during the pre-establishment phase with a Local 1417 Endpoint specifier, as well as all properties necessary for Protocol 1418 Stack selection. A Remote Endpoint may optionally be specified, to 1419 constrain what Connections are accepted. 1421 The Listen() Action returns a Listener object. Once Listen() has 1422 been called, any changes to the Preconnection MUST NOT have any 1423 effect on the Listener. The Preconnection can be disposed of or 1424 reused, e.g., to create another Listener. 1426 Listening continues until the global context shuts down, or until the 1427 Stop action is performed on the Listener object: 1429 Listener.Stop() 1431 After Stop() is called, the Listener can be disposed of. 1433 Listener -> ConnectionReceived 1435 The ConnectionReceived Event occurs when a Remote Endpoint has 1436 established a transport-layer connection to this Listener (for 1437 Connection-oriented transport protocols), or when the first Message 1438 has been received from the Remote Endpoint (for Connectionless 1439 protocols), causing a new Connection to be created. The resulting 1440 Connection is contained within the ConnectionReceived Event, and is 1441 ready to use as soon as it is passed to the application via the 1442 event. 1444 Listener.SetNewConnectionLimit(value) 1445 If the caller wants to rate-limit the number of inbound Connections 1446 that will be delivered, it can set a cap using 1447 SetNewConnectionLimit(). This mechanism allows a server to protect 1448 itself from being drained of resources. Each time a new Connection 1449 is delivered by the ConnectionReceived Event, the value is 1450 automatically decremented. Once the value reaches zero, no further 1451 Connections will be delivered until the caller sets the limit to a 1452 higher value. By default, this value is Infinite. The caller is 1453 also able to reset the value to Infinite at any point. 1455 Listener -> EstablishmentError 1457 An EstablishmentError occurs either when the Properties and Security 1458 Parameters of the Preconnection cannot be fulfilled for listening or 1459 cannot be reconciled with the Local Endpoint (and/or Remote Endpoint, 1460 if specified), when the Local Endpoint (or Remote Endpoint, if 1461 specified) cannot be resolved, or when the application is prohibited 1462 from listening by policy. 1464 Listener -> Stopped<> 1466 A Stopped Event occurs after the Listener has stopped listening. 1468 6.3. Peer-to-Peer Establishment: Rendezvous 1470 Simultaneous peer-to-peer Connection establishment is supported by 1471 the Rendezvous() Action: 1473 Preconnection.Rendezvous() 1475 The Preconnection Object must be specified with both a Local Endpoint 1476 and a Remote Endpoint, and also the transport properties and security 1477 parameters needed for Protocol Stack selection. 1479 The Rendezvous() Action causes the Preconnection to listen on the 1480 Local Endpoint for an incoming Connection from the Remote Endpoint, 1481 while simultaneously trying to establish a Connection from the Local 1482 Endpoint to the Remote Endpoint. This corresponds to a TCP 1483 simultaneous open, for example. 1485 The Rendezvous() Action returns a Connection object. Once 1486 Rendezvous() has been called, any changes to the Preconnection MUST 1487 NOT have any effect on the Connection. However, the Preconnection 1488 can be reused, e.g., for Rendezvous of another Connection. 1490 Preconnection -> RendezvousDone 1491 The RendezvousDone<> Event occurs when a Connection is established 1492 with the Remote Endpoint. For Connection-oriented transports, this 1493 occurs when the transport-layer connection is established; for 1494 Connectionless transports, it occurs when the first Message is 1495 received from the Remote Endpoint. The resulting Connection is 1496 contained within the RendezvousDone<> Event, and is ready to use as 1497 soon as it is passed to the application via the Event. 1499 Preconnection -> EstablishmentError 1501 An EstablishmentError occurs either when the Properties and Security 1502 Parameters of the Preconnection cannot be fulfilled for rendezvous or 1503 cannot be reconciled with the Local and/or Remote Endpoints, when the 1504 Local Endpoint or Remote Endpoint cannot be resolved, when no 1505 transport-layer connection can be established to the Remote Endpoint, 1506 or when the application is prohibited from rendezvous by policy. 1508 When using some NAT traversal protocols, e.g., Interactive 1509 Connectivity Establishment (ICE) [RFC5245], it is expected that the 1510 Local Endpoint will be configured with some method of discovering NAT 1511 bindings, e.g., a Session Traversal Utilities for NAT (STUN) server. 1512 In this case, the Local Endpoint may resolve to a mixture of local 1513 and server reflexive addresses. The Resolve() action on the 1514 Preconnection can be used to discover these bindings: 1516 []Preconnection := Preconnection.Resolve() 1518 The Resolve() call returns a list of Preconnection Objects, that 1519 represent the concrete addresses, local and server reflexive, on 1520 which a Rendezvous() for the Preconnection will listen for incoming 1521 Connections. These resolved Preconnections will share all other 1522 Properties with the Preconnection from which they are derived, though 1523 some Properties may be made more-specific by the resolution process. 1524 This list can be passed to a peer via a signalling protocol, such as 1525 SIP [RFC3261] or WebRTC [RFC7478], to configure the remote. 1527 6.4. Connection Groups 1529 Entangled Connections can be created using the Clone Action: 1531 Connection := Connection.Clone() 1533 Calling Clone on a Connection yields a group of two Connections: the 1534 parent Connection on which Clone was called, and the resulting cloned 1535 Connection. These connections are "entangled" with each other, and 1536 become part of a Connection Group. Calling Clone on any of these two 1537 Connections adds a third Connection to the Connection Group, and so 1538 on. Connections in a Connection Group generally share Connection 1539 Properties. However, there may be exceptions, such as "Priority 1540 (Connection)", see Section 7.1.3. Like all other Properties, 1541 Priority is copied to the new Connection when calling Clone(), but it 1542 is not entangled: Changing Priority on one Connection does not change 1543 it on the other Connections in the same Connection Group. 1545 It is also possible to check which Connections belong to the same 1546 Connection Group. Calling GroupedConnections() on a specific 1547 Connection returns a set of all Connections in the same group. 1549 []Connection := Connection.GroupedConnections() 1551 Connections will be in the same group if the application previously 1552 called Clone. Passive Connections can also be added to the same 1553 group - e.g., when a Listener receives a new Connection that is just 1554 a new stream of an already active multi-streaming protocol instance. 1556 Changing one of the Connection Properties on one Connection in the 1557 group changes it for all others. Message Properties, however, are 1558 not entangled. For example, changing "Timeout for aborting 1559 Connection" (see Section 7.1.4) on one Connection in a group will 1560 automatically change this Connection Property for all Connections in 1561 the group in the same way. However, changing "Lifetime" (see 1562 Section 8.1.3.1) of a Message will only affect a single Message on a 1563 single Connection, entangled or not. 1565 If the underlying protocol supports multi-streaming, it is natural to 1566 use this functionality to implement Clone. In that case, entangled 1567 Connections are multiplexed together, giving them similar treatment 1568 not only inside endpoints but also across the end-to-end Internet 1569 path. 1571 Note that calling Clone() may result in on-the-wire signaling, e.g., 1572 to open a new connection, depending on the underlying Protocol Stack. 1573 When Clone() leads to multiple connections being opened instead of 1574 multi-streaming, the transport system will ensure consistency of 1575 Connection Properties by uniformly applying them to all underlying 1576 connections in a group. Even in such a case, there are possibilities 1577 for a transport system to implement prioritization within a 1578 Connection Group [TCP-COUPLING] [RFC8699]. 1580 Attempts to clone a Connection can result in a CloneError: 1582 Connection -> CloneError 1584 The Connection Property "Priority" operates on entangled Connections 1585 as in Section 8.1.3.2: when allocating available network capacity 1586 among Connections in a Connection Group, sends on Connections with 1587 higher Priority values will be prioritized over sends on Connections 1588 with lower Priority values. A transport system implementation 1589 should, if possible, assign each Connection the capacity share (M-N) 1590 x C / M, where N is the Connection's Priority value, M is the maximum 1591 Priority value used by all Connections in the group and C is the 1592 total available capacity. However, the Priority setting is purely 1593 advisory, and no guarantees are given about the way capacity is 1594 shared. Each implementation is free to implement a way to share 1595 capacity that it sees fit. 1597 7. Managing Connections 1599 During pre-establishment and after establishment, connections can be 1600 configured and queried using Connection Properties, and asynchronous 1601 information may be available about the state of the connection via 1602 Soft Errors. 1604 Connection Properties represent the configuration and state of the 1605 selected Protocol Stack(s) backing a Connection. These Connection 1606 Properties may be Generic, applying regardless of transport protocol, 1607 or Specific, applicable to a single implementation of a single 1608 transport protocol stack. Generic Connection Properties are defined 1609 in Section 7.1 below. Specific Protocol Properties are defined in a 1610 transport- and implementation-specific way, and must not be assumed 1611 to apply across different protocols. Attempts to set Specific 1612 Protocol Properties on a protocol stack not containing that specific 1613 protocol are simply ignored, and do not raise an error; however, too 1614 much reliance by an application on Specific Protocol Properties may 1615 significantly reduce the flexibility of a transport services 1616 implementation. 1618 The application can set and query Connection Properties on a per- 1619 Connection basis. Connection Properties that are not read-only can 1620 be set during pre-establishment (see Section 5.2), as well as on 1621 connections directly using the SetProperty action: 1623 Connection.SetProperty(property, value) 1625 Note that changing one of the Connection Properties on one Connection 1626 in a Connection Group will also change it for all other Connections 1627 of that group; see further Section 6.4. 1629 At any point, the application can query Connection Properties. 1631 ConnectionProperties := Connection.GetProperties() 1633 Depending on the status of the connection, the queried Connection 1634 Properties will include different information: 1636 o The connection state, which can be one of the following: 1637 Establishing, Established, Closing, or Closed. 1639 o Whether the connection can be used to send data. A connection can 1640 not be used for sending if the connection was created with the 1641 Selection Property "Direction of Communication" set to 1642 "unidirectional receive" or if a Message marked as "Final" was 1643 sent over this connection, see Section 8.1.3.5. 1645 o Whether the connection can be used to receive data. A connection 1646 can not be used for reading if the connection was created with the 1647 Selection Property "Direction of Communication" set to 1648 "unidirectional send" or if a Message marked as "Final" was 1649 received, see Section 8.3.3.3. The latter is only supported by 1650 certain transport protocols, e.g., by TCP as half-closed 1651 connection. 1653 o For Connections that are Establishing: Transport Properties that 1654 the application specified on the Preconnection, see Section 5.2. 1656 o For Connections that are Established, Closing, or Closed: 1657 Selection (Section 5.2) and Connection Properties (Section 7.1) of 1658 the actual protocols that were selected and instantiated. 1659 Selection Properties indicate whether or not the Connection has or 1660 offers a certain Selection Property. Note that the actually 1661 instantiated protocol stack may not match all Protocol Selection 1662 Properties that the application specified on the Preconnection. 1663 For example, a certain Protocol Selection Property that an 1664 application specified as Preferred may not actually be present in 1665 the chosen protocol stack because none of the currently available 1666 transport protocols had this feature. 1668 o For Connections that are Established, additional properties of the 1669 path(s) in use. These properties can be derived from the local 1670 provisioning domain [RFC7556], measurements by the Protocol Stack, 1671 or other sources. 1673 7.1. Generic Connection Properties 1675 Generic Connection Properties are defined independent of the chosen 1676 protocol stack and therefore available on all Connections. 1678 Note that many Connection Properties have a corresponding Selection 1679 Property which enables applications to express their preference for 1680 protocols providing a supporting transport feature. 1682 7.1.1. Retransmission Threshold Before Excessive Retransmission 1683 Notification 1685 Name: retransmitNotifyThreshold 1687 Type: Integer, with special value "Disabled" 1689 Default: Disabled 1691 This property specifies after how many retransmissions to inform the 1692 application about "Excessive Retransmissions". 1694 7.1.2. Required Minimum Corruption Protection Coverage for Receiving 1696 Name: recvChecksumLen 1698 Type: Integer, with special value "Full Coverage" 1700 Default: Full Coverage 1702 This property specifies the part of the received data that needs to 1703 be covered by a checksum. It is given in Bytes. A value of 0 means 1704 that no checksum is required. 1706 7.1.3. Priority (Connection) 1708 Name: connPrio 1710 Type: Integer 1712 Default: 100 1714 This Property is a non-negative integer representing the relative 1715 inverse priority (i.e., a lower value reflects a higher priority) of 1716 this Connection relative to other Connections in the same Connection 1717 Group. It has no effect on Connections not part of a Connection 1718 Group. As noted in Section 6.4, this property is not entangled when 1719 Connections are cloned, i.e., changing the Priority on one Connection 1720 in a Connection Group does not change it on the other Connections in 1721 the same Connection Group. 1723 7.1.4. Timeout for Aborting Connection 1725 Name: connTimeout 1727 Type: Numeric, with special value "Disabled" 1729 Default: Disabled 1730 This property specifies how long to wait before deciding that a 1731 Connection has failed when trying to reliably deliver data to the 1732 destination. Adjusting this Property will only take effect when the 1733 underlying stack supports reliability. The special value "Disabled" 1734 means that this timeout is not scheduled to happen. This can be a 1735 valid choice with unreliable data transfer (e.g., when UDP is the 1736 underlying transport protocol). 1738 7.1.5. Connection Group Transmission Scheduler 1740 Name: connScheduler 1742 Type: Enumeration 1744 Default: Weighted Fair Queueing (see Section 3.6 in [RFC8260]) 1746 This property specifies which scheduler should be used among 1747 Connections within a Connection Group, see Section 6.4. The set of 1748 schedulers can be taken from [RFC8260]. 1750 7.1.6. Capacity Profile 1752 Name: connCapacityProfile 1754 This property specifies the desired network treatment for traffic 1755 sent by the application and the tradeoffs the application is prepared 1756 to make in path and protocol selection to receive that desired 1757 treatment. When the capacity profile is set to a value other than 1758 Default, the transport system SHOULD select paths and configure 1759 protocols to optimize the tradeoff between delay, delay variation, 1760 and efficient use of the available capacity based on the capacity 1761 profile specified. How this is realized is implementation-specific. 1762 The Capacity Profile MAY also be used to set priorities on the wire 1763 for Protocol Stacks supporting prioritization. Recommendations for 1764 use with DSCP are provided below for each profile; note that when a 1765 Connection is multiplexed, the guidelines in Section 6 of [RFC7657] 1766 apply. 1768 The following values are valid for the Capacity Profile: 1770 Default: The application provides no information about its expected 1771 capacity profile. Transport system implementations that map the 1772 requested capacity profile onto per-connection DSCP signaling 1773 SHOULD assign the DSCP Default Forwarding [RFC2474] PHB. 1775 Scavenger: The application is not interactive. It expects to send 1776 and/or receive data without any urgency. This can, for example, 1777 be used to select protocol stacks with scavenger transmission 1778 control and/or to assign the traffic to a lower-effort service. 1779 Transport system implementations that map the requested capacity 1780 profile onto per-connection DSCP signaling SHOULD assign the DSCP 1781 Less than Best Effort [RFC8622] PHB. 1783 Low Latency/Interactive: The application is interactive, and prefers 1784 loss to latency. Response time should be optimized at the expense 1785 of delay variation and efficient use of the available capacity 1786 when sending on this connection. This can be used by the system 1787 to disable the coalescing of multiple small Messages into larger 1788 packets (Nagle's algorithm); to prefer immediate acknowledgment 1789 from the peer endpoint when supported by the underlying transport; 1790 and so on. Transport system implementations that map the 1791 requested capacity profile onto per-connection DSCP signaling 1792 without multiplexing SHOULD assign a DSCP Assured Forwarding 1793 (AF41,AF42,AF43,AF44) [RFC2597] PHB. Inelastic traffic that is 1794 expected to conform to the configured network service rate could 1795 be mapped to the DSCP Expedited Forwarding [RFC3246] or [RFC5865] 1796 PHBs. 1798 Low Latency/Non-Interactive: The application prefers loss to latency 1799 but is not interactive. Response time should be optimized at the 1800 expense of delay variation and efficient use of the available 1801 capacity when sending on this connection. Transport system 1802 implementations that map the requested capacity profile onto per- 1803 connection DSCP signaling without multiplexing SHOULD assign a 1804 DSCP Assured Forwarding (AF21,AF22,AF23,AF24) [RFC2597] PHB. 1806 Constant-Rate Streaming: The application expects to send/receive 1807 data at a constant rate after Connection establishment. Delay and 1808 delay variation should be minimized at the expense of efficient 1809 use of the available capacity. This implies that the Connection 1810 may fail if the desired rate cannot be maintained across the Path. 1811 A transport may interpret this capacity profile as preferring a 1812 circuit breaker [RFC8084] to a rate-adaptive congestion 1813 controller. Transport system implementations that map the 1814 requested capacity profile onto per-connection DSCP signaling 1815 without multiplexing SHOULD assign a DSCP Assured Forwarding 1816 (AF31,AF32,AF33,AF34) [RFC2597] PHB. 1818 Capacity-Seeking: The application expects to send/receive data at 1819 the maximum rate allowed by its congestion controller over a 1820 relatively long period of time. Transport system implementations 1821 that map the requested capacity profile onto per-connection DSCP 1822 signaling without multiplexing SHOULD assign a DSCP Assured 1823 Forwarding (AF11,AF12,AF13,AF14) [RFC2597] PHB per Section 4.8 of 1824 [RFC4594]. 1826 The Capacity Profile for a selected protocol stack may be modified on 1827 a per-Message basis using the Transmission Profile Message Property; 1828 see Section 8.1.3.8. 1830 7.1.7. Policy for using Multi-Path Transports 1832 Name: multipath-policy 1834 Type: Enumeration 1836 Default: Handover 1838 This property specifies the local policy of transferring data across 1839 multiple paths between the same end hosts if Parallel Use of Multiple 1840 Paths not set to Disabled (see Section 5.2.13). Possible values are: 1842 Handover: The connection should only attempt to migrate between 1843 different paths when the original path is lost or becomes 1844 unusable. The actual thresholds to declare a path unusable are 1845 implementation specific. 1847 Interactive: The connection should attempt to minimize the latency 1848 for interactive traffic patterns by transmitting data across 1849 multiple paths when it is beneficial to do so. The goal of 1850 minimizing the latency will be balanced against the cost of each 1851 of these paths, meaning that depending on the cost of the lower- 1852 latency path, the scheduling might choose to use a higher-latency 1853 path. Traffic can be scheduled such that data may be transmitted 1854 on multiple paths in parallel to achieve the lowest latency 1855 possible. The specific scheduling algorithm is implementation- 1856 specific. 1858 Aggregate: The connection should attempt to use multiple paths in 1859 parallel in order to maximize bandwidth and possibly overcome 1860 bandwidth limitations of the individual paths. The actual 1861 strategy is implementation specific. 1863 Note that this is a local choice - the peer endpoint can choose a 1864 different policy. 1866 7.1.8. Bounds on Send or Receive Rate 1868 Name: maxSendRate / maxRecvRate 1870 Type: Numeric (with special value "Unlimited") / Numeric (with 1871 special value "Unlimited") 1873 Default: Unlimited / Unlimited 1874 This property specifies an upper-bound rate that a transfer is not 1875 expected to exceed (even if flow control and congestion control allow 1876 higher rates), and/or a lower-bound rate below which the application 1877 does not deem a data transfer useful. It is given in bits per 1878 second. The special value "Unlimited" indicates that no bound is 1879 specified. 1881 7.1.9. Read-only Connection Properties 1883 The following generic Connection Properties are read-only, i.e. they 1884 cannot be changed by an application. 1886 7.1.9.1. Maximum Message Size Concurrent with Connection Establishment 1888 Name: zeroRttMsgMaxLen 1890 Type: Integer 1892 This property represents the maximum Message size that can be sent 1893 before or during Connection establishment, see also Section 8.1.3.4. 1894 It is given in Bytes. 1896 7.1.9.2. Maximum Message Size Before Fragmentation or Segmentation 1898 Name: singularTransmissionMsgMaxLen 1900 Type: Integer 1902 This property, if applicable, represents the maximum Message size 1903 that can be sent without incurring network-layer fragmentation or 1904 transport layer segmentation at the sender. This property exposes 1905 the Maximum Packet Size (MPS) as described in Datagram PLPMTUD 1906 [I-D.ietf-tsvwg-datagram-plpmtud]. 1908 7.1.9.3. Maximum Message Size on Send 1910 Name: sendMsgMaxLen 1912 Type: Integer 1914 This property represents the maximum Message size that can be sent 1915 using a send operation. 1917 7.1.9.4. Maximum Message Size on Receive 1919 Name: recvMsgMaxLen 1921 Type: Integer 1922 This numeric property represents the maximum Message size that can be 1923 received. 1925 7.2. TCP-specific Properties: User Timeout Option (UTO) 1927 These properties specify configurations for the User Timeout Option 1928 (UTO), in case TCP becomes the chosen transport protocol. 1929 Implementation is optional and of course only sensible if TCP is 1930 implemented in the transport system. 1932 These TCP-specific properties are included here because the feature 1933 "Suggest timeout to the peer" is part of the minimal set of transport 1934 services [I-D.ietf-taps-minset], where this feature was categorized 1935 as "functional". This means that when an implementation offers this 1936 feature, it has to expose an interface to it to the application. 1937 Otherwise, the implementation might violate assumptions by the 1938 application, which could cause the application to fail. 1940 All of the below properties are optional (e.g., it is possible to 1941 specify "User Timeout Enabled" as true, but not specify an Advertised 1942 User Timeout value; in this case, the TCP default will be used). 1944 7.2.1. Advertised User Timeout 1946 Name: tcp.userTimeoutValue 1948 Type: Integer 1950 Default: the TCP default 1952 This time value is advertised via the TCP User Timeout Option (UTO) 1953 [RFC5482] at the remote endpoint to adapt its own "Timeout for 1954 aborting Connection" (see Section 7.1.4) value accordingly. 1956 7.2.2. User Timeout Enabled 1958 Name: tcp.userTimeout 1960 Type: Boolean 1962 Default: false 1964 This property controls whether the UTO option is enabled for a 1965 connection. This applies to both sending and receiving. 1967 7.2.3. Timeout Changeable 1969 Name: tcp.userTimeoutRecv 1971 Type: Boolean 1973 Default: true 1975 This property controls whether the "Timeout for aborting Connection" 1976 (see Section 7.1.4) may be changed based on a UTO option received 1977 from the remote peer. This boolean becomes false when "Timeout for 1978 aborting Connection" (see Section 7.1.4) is used. 1980 7.3. Connection Lifecycle Events 1982 During the lifetime of a connection there are events that can occur 1983 when configured. 1985 7.3.1. Soft Errors 1987 Asynchronous introspection is also possible, via the SoftError Event. 1988 This event informs the application about the receipt and contents of 1989 an ICMP error message related to the Connection. This will only 1990 happen if the underlying protocol stack supports access to soft 1991 errors; however, even if the underlying stack supports it, there is 1992 no guarantee that a soft error will be signaled. 1994 Connection -> SoftError<> 1996 7.3.2. Excessive retransmissions 1998 This event notifies the application of excessive retransmissions, 1999 based on a configured threshold (see Section 7.1.1). This will only 2000 happen if the underlying protocol stack supports reliability and, 2001 with it, such notifications. 2003 Connection -> ExcessiveRetransmission<> 2005 8. Data Transfer 2007 Data is sent and received as Messages, which allows the application 2008 to communicate the boundaries of the data being transferred. 2010 8.1. Messages and Framers 2012 Each Message has an optional Message Context, which allows to add 2013 Message Properties, identify Send Events related to a specific 2014 Message or to inspect meta-data related to the Message sent. Framers 2015 can be used to extend or modify the message data with additional 2016 information that can be processed at the receiver to detect message 2017 boundaries. 2019 8.1.1. Message Contexts 2021 Using the MessageContext object, the application can set and retrieve 2022 meta-data of the message, including Message Properties (see 2023 Section 8.1.3) and framing meta-data (see Section 8.1.2.2). 2024 Therefore, a MessageContext object can be passed to the Send action 2025 and is returned by each Send and Receive related event. 2027 Message Properties can be set and queried using the Message Context: 2029 MessageContext.add(scope?, parameter, value) 2030 PropertyValue := MessageContext.get(scope?, property) 2032 To get or set Message Properties, the optional scope parameter is 2033 left empty. To get or set meta-data for a Framer, the application 2034 has to pass a reference to this Framer as the scope parameter. 2036 For MessageContexts returned by send events (see Section 8.2.3) and 2037 receive events (see Section 8.3.2), the application can query 2038 information about the local and remote endpoint: 2040 RemoteEndpoint := MessageContext.GetRemoteEndpoint() 2041 LocalEndpoint := MessageContext.GetLocalEndpoint() 2043 Message Contexts can also be used to send messages in reply to other 2044 messages, see Section 8.2.2 for details. 2046 8.1.2. Message Framers 2048 Although most applications communicate over a network using well- 2049 formed Messages, the boundaries and metadata of the Messages are 2050 often not directly communicated by the transport protocol itself. 2051 For example, HTTP applications send and receive HTTP messages over a 2052 byte-stream transport, requiring that the boundaries of HTTP messages 2053 be parsed out from the stream of bytes. 2055 Message Framers allow extending a Connection's Protocol Stack to 2056 define how to encapsulate or encode outbound Messages, and how to 2057 decapsulate or decode inbound data into Messages. Message Framers 2058 allow message boundaries to be preserved when using a Connection 2059 object, even when using byte-stream transports. This facility is 2060 designed based on the fact that many of the current application 2061 protocols evolved over TCP, which does not provide message boundary 2062 preservation, and since many of these protocols require message 2063 boundaries to function, each application layer protocol has defined 2064 its own framing. 2066 To use a Message Framer, the application adds it to its Preconnection 2067 object. Then, the Message Framer can intercept all calls to Send() 2068 or Receive() on a Connection to add Message semantics, in addition to 2069 interacting with the setup and teardown of the Connection. A Framer 2070 can start sending data before the application sends data if the 2071 framing protocol requires a prefix or handshake (see [RFC8229] for an 2072 example of such a framing protocol). 2074 Initiate() Send() Receive() Close() 2075 | | ^ | 2076 | | | | 2077 +----v----------v---------+----------v-----+ 2078 | Connection | 2079 +----+----------+---------^----------+-----+ 2080 | | | | 2081 | +-----------------+ | 2082 | | Messages | | 2083 | +-----------------+ | 2084 | | | | 2085 +----v----------v---------+----------v-----+ 2086 | Framer(s) | 2087 +----+----------+---------^----------+-----+ 2088 | | | | 2089 | +-----------------+ | 2090 | | Byte-stream | | 2091 | +-----------------+ | 2092 | | | | 2093 +----v----------v---------+----------v-----+ 2094 | Transport Protocol Stack | 2095 +------------------------------------------+ 2097 Note that while Message Framers add the most value when placed above 2098 a protocol that otherwise does not preserve message boundaries, they 2099 can also be used with datagram- or message-based protocols. In these 2100 cases, they add an additional transformation to further encode or 2101 encapsulate, and can potentially support packing multiple 2102 application-layer Messages into individual transport datagrams. 2104 The API to implement a Message Framer can vary depending on the 2105 implementation; guidance on implementing Message Framers can be found 2106 in [I-D.ietf-taps-impl]. 2108 8.1.2.1. Adding Message Framers to Connections 2110 The Message Framer object can be added to one or more Preconnections 2111 to run on top of transport protocols. Multiple Framers may be added. 2112 If multiple Framers are added, the last one added runs first when 2113 framing outbound messages, and last when parsing inbound data. 2115 The following example adds a basic HTTP Message Framer to a 2116 Preconnection: 2118 framer := NewHTTPMessageFramer() 2119 Preconnection.AddFramer(framer) 2121 8.1.2.2. Framing Meta-Data 2123 When sending Messages, applications can add specific Message values 2124 to a MessageContext (Section 8.1.1) that is intended for a Framer. 2125 This can be used, for example, to set the type of a Message for a TLV 2126 format. The namespace of values is custom for each unique Message 2127 Framer. 2129 messageContext := NewMessageContext() 2130 messageContext.add(framer, key, value) 2131 Connection.Send(messageData, messageContext) 2133 When an application receives a MessageContext in a Receive event, it 2134 can also look to see if a value was set by a specific Message Framer. 2136 messageContext.get(framer, key) -> value 2138 For example, if an HTTP Message Framer is used, the values could 2139 correspond to HTTP headers: 2141 httpFramer := NewHTTPMessageFramer() 2142 ... 2143 messageContext := NewMessageContext() 2144 messageContext.add(httpFramer, "accept", "text/html") 2146 8.1.3. Message Properties 2148 Applications may need to annotate the Messages they send with extra 2149 information to control how data is scheduled and processed by the 2150 transport protocols in the Connection. Therefore a message context 2151 containing these properties can be passed to the Send Action. For 2152 other uses of the message context, see Section 8.1.1. 2154 Note that Message Properties are per-Message, not per-Send if partial 2155 Messages are sent (Section 8.2.4). All data blocks associated with a 2156 single Message share properties specified in the Message Contexts. 2157 For example, it would not make sense to have the beginning of a 2158 Message expire, but allow the end of a Message to still be sent. 2160 A MessageContext object contains metadata for Messages to be sent or 2161 received. 2163 messageData := "hello" 2164 messageContext := NewMessageContext() 2165 messageContext.add(parameter, value) 2166 Connection.Send(messageData, messageContext) 2168 The simpler form of Send, which does not take any messageContext, is 2169 equivalent to passing a default MessageContext without adding any 2170 Message Properties to it. 2172 If an application wants to override Message Properties for a specific 2173 message, it can acquire an empty MessageContext Object and add all 2174 desired Message Properties to that Object. It can then reuse the 2175 same messageContext Object for sending multiple Messages with the 2176 same properties. 2178 Properties may be added to a MessageContext object only before the 2179 context is used for sending. Once a messageContext has been used 2180 with a Send call, modifying any of its properties is invalid. 2182 Message Properties may be inconsistent with the properties of the 2183 Protocol Stacks underlying the Connection on which a given Message is 2184 sent. For example, a Connection must provide reliability to allow 2185 setting an infinite value for the lifetime property of a Message. 2186 Sending a Message with Message Properties inconsistent with the 2187 Selection Properties of the Connection yields an error. 2189 Connection Properties describe the default behavior for all Messages 2190 on a Connection. If a Message Property contradicts a Connection 2191 Property, and if this per-Message behavior can be supported, it 2192 overrides the Connection Property for the specific Message. For 2193 example, if "Reliable Data Transfer (Connection)" is set to "Require" 2194 and a protocol with configurable per-Message reliability is used, 2195 setting "Reliable Data Transfer (Message)" to "false" for a 2196 particular Message will allow this Message to be unreliably 2197 delivered. Note that changing the Reliable Data Transfer property on 2198 Messages is only possible for Connections that were established with 2199 the Selection Property "Configure Per-Message Reliability" enabled. 2201 The following Message Properties are supported: 2203 8.1.3.1. Lifetime 2205 Name: msgLifetime 2207 Type: Numeric 2209 Default: infinite 2211 Lifetime specifies how long a particular Message can wait to be sent 2212 to the remote endpoint before it is irrelevant and no longer needs to 2213 be (re-)transmitted. This is a hint to the transport system - it is 2214 not guaranteed that a Message will not be sent when its Lifetime has 2215 expired. 2217 Setting a Message's Lifetime to infinite indicates that the 2218 application does not wish to apply a time constraint on the 2219 transmission of the Message, but it does not express a need for 2220 reliable delivery; reliability is adjustable per Message via the 2221 "Reliable Data Transfer (Message)" property (see Section 8.1.3.7). 2222 The type and units of Lifetime are implementation-specific. 2224 8.1.3.2. Priority 2226 Name: msgPrio 2228 Type: Integer (non-negative) 2230 Default: 100 2232 This property represents a hierarchy of priorities. It can specify 2233 the priority of a Message, relative to other Messages sent over the 2234 same Connection. 2236 A Message with Priority 0 will yield to a Message with Priority 1, 2237 which will yield to a Message with Priority 2, and so on. Priorities 2238 may be used as a sender-side scheduling construct only, or be used to 2239 specify priorities on the wire for Protocol Stacks supporting 2240 prioritization. 2242 Note that this property is not a per-message override of the 2243 connection Priority - see Section 7.1.3. Both Priority properties 2244 may interact, but can be used independently and be realized by 2245 different mechanisms. 2247 8.1.3.3. Ordered 2249 Name: msgOrdered 2251 Type: Boolean 2253 Default: true 2255 If true, it specifies that the receiver-side transport protocol stack 2256 may only deliver the Message to the receiving application after the 2257 previous ordered Message which was passed to the same Connection via 2258 the Send Action, when such a Message exists. If false, the Message 2259 may be delivered to the receiving application out of order. This 2260 property is used for protocols that support preservation of data 2261 ordering, see Section 5.2.4, but allow out-of-order delivery for 2262 certain messages, e.g., by multiplexing independent messages onto 2263 different streams. 2265 8.1.3.4. Safely Replayable 2267 Name: safelyReplayable 2269 Type: Boolean 2271 Default: false 2273 If true, it specifies that a Message is safe to send to the remote 2274 endpoint more than once for a single Send Action. It is used to mark 2275 data safe for certain 0-RTT establishment techniques, where 2276 retransmission of the 0-RTT data may cause the remote application to 2277 receive the Message multiple times. 2279 Note that for protocols that do not protect against duplicated 2280 messages, e.g., UDP, all messages MUST be marked as "Safely 2281 Replayable". In order to enable protocol selection to choose such a 2282 protocol, "Safely Replayable" MUST be added to the 2283 TransportProperties passed to the Preconnection. If such a protocol 2284 was chosen, disabling "Safely Replayable" on individual messages MUST 2285 result in a SendError. 2287 8.1.3.5. Final 2289 Name: final 2291 Type: Boolean 2293 Default: false 2294 If true, this Message is the last one that the application will send 2295 on a Connection. This allows underlying protocols to indicate to the 2296 Remote Endpoint that the Connection has been effectively closed in 2297 the sending direction. For example, TCP-based Connections can send a 2298 FIN once a Message marked as Final has been completely sent, 2299 indicated by marking endOfMessage. Protocols that do not support 2300 signalling the end of a Connection in a given direction will ignore 2301 this property. 2303 Note that a Final Message must always be sorted to the end of a list 2304 of Messages. The Final property overrides Priority and any other 2305 property that would re-order Messages. If another Message is sent 2306 after a Message marked as Final has already been sent on a 2307 Connection, the Send Action for the new Message will cause a 2308 SendError Event. 2310 8.1.3.6. Corruption Protection Length 2312 Name: msgChecksumLen 2314 Type: Integer (non-negative with special value "Full Coverage") 2316 Default: Full Coverage 2318 This property specifies the minimum length of the section of the 2319 Message, starting from byte 0, that the application requires to be 2320 delivered without corruption due to lower layer errors. It is used 2321 to specify options for simple integrity protection via checksums. A 2322 value of 0 means that no checksum is required, and "Full Coverage" 2323 means that the entire Message is protected by a checksum. Only "Full 2324 Coverage" is guaranteed, any other requests are advisory, meaning 2325 that "Full Coverage" is applied anyway. 2327 8.1.3.7. Reliable Data Transfer (Message) 2329 Name: msgReliable 2331 Type: Boolean 2333 Default: true 2335 When true, this property specifies that a message should be sent in 2336 such a way that the transport protocol ensures all data is received 2337 on the other side without corruption. Changing the "Reliable Data 2338 Transfer" property on Messages is only possible for Connections that 2339 were established with the Selection Property "Configure Per-Message 2340 Reliability" enabled. When this is not the case, changing it will 2341 generate an error. Disabling this property indicates that the 2342 transport system may disable retransmissions or other reliability 2343 mechanisms for this particular Message, but such disabling is not 2344 guaranteed. 2346 8.1.3.8. Message Capacity Profile Override 2348 Name: msgCapacityProfile 2350 Type: Enumeration 2352 This enumerated property specifies the application's preferred 2353 tradeoffs for sending this Message; it is a per-Message override of 2354 the Capacity Profile connection property (see Section 7.1.6). 2356 8.1.3.9. No Fragmentation 2358 Name: noFragmentation 2360 Type: Boolean 2362 Default: false 2364 This property specifies that a message should be sent and received as 2365 a single packet without network-layer fragmentation, if possible. 2366 Attempts to send a message with this property set with a size greater 2367 to the transport's current estimate of its maximum transmission 2368 segment size will result in a "SendError". When used with transports 2369 supporting this functionality and running over IP version 4, the 2370 Don't Fragment bit will be set. 2372 8.2. Sending Data 2374 Once a Connection has been established, it can be used for sending 2375 Messages. By default, Send enqueues a complete Message, and takes 2376 optional per-Message properties (see Section 8.2.1). All Send 2377 actions are asynchronous, and deliver events (see Section 8.2.3). 2378 Sending partial Messages for streaming large data is also supported 2379 (see Section 8.2.4). 2381 Messages are sent on a Connection using the Send action: 2383 Connection.Send(messageData, messageContext?, endOfMessage?) 2385 where messageData is the data object to send, and messageContext 2386 allows adding Message Properties, identifying Send Events related to 2387 a specific Message or inspecting meta-data related to the Message 2388 sent (see Section 8.1.1). 2390 The optional endOfMessage parameter supports partial sending and is 2391 described in Section 8.2.4. 2393 8.2.1. Basic Sending 2395 The most basic form of sending on a connection involves enqueuing a 2396 single Data block as a complete Message, with default Message 2397 Properties. 2399 messageData := "hello" 2400 Connection.Send(messageData) 2402 The interpretation of a Message to be sent is dependent on the 2403 implementation, and on the constraints on the Protocol Stacks implied 2404 by the Connection's transport properties. For example, a Message may 2405 be a single datagram for UDP Connections; or an HTTP Request for HTTP 2406 Connections. 2408 Some transport protocols can deliver arbitrarily sized Messages, but 2409 other protocols constrain the maximum Message size. Applications can 2410 query the Connection Property "Maximum Message size on send" 2411 (Section 7.1.9.3) to determine the maximum size allowed for a single 2412 Message. If a Message is too large to fit in the Maximum Message 2413 Size for the Connection, the Send will fail with a SendError event 2414 (Section 8.2.3.3). For example, it is invalid to send a Message over 2415 a UDP connection that is larger than the available datagram sending 2416 size. 2418 8.2.2. Sending Replies 2420 When a message is sent in response to a message received, the 2421 application may use the Message Context of the received Message to 2422 construct a Message Context for the reply. 2424 replyMessageContext := requestMessageContext.reply() 2426 By using the "replyMessageContext", the transport system is informed 2427 that the message to be sent is a response and can map the response to 2428 the same underlying transport connection or stream the request was 2429 received from. The concept of Message Contexts is described in 2430 Section 8.1.1. 2432 8.2.3. Send Events 2434 Like all Actions in this interface, the Send Action is asynchronous. 2435 There are several Events that can be delivered in response to Sending 2436 a Message. Exactly one Event (Sent, Expired, or SendError) will be 2437 delivered in response to each call to Send. 2439 Note that if partial Sends are used (Section 8.2.4), there will still 2440 be exactly one Send Event delivered for each call to Send. For 2441 example, if a Message expired while two requests to Send data for 2442 that Message are outstanding, there will be two Expired events 2443 delivered. 2445 The interface should allow the application to correlate which Send 2446 Action resulted in a particular Send Event. The manner in which this 2447 correlation is indicated is implementation-specific. 2449 8.2.3.1. Sent 2451 Connection -> Sent 2453 The Sent Event occurs when a previous Send Action has completed, 2454 i.e., when the data derived from the Message has been passed down or 2455 through the underlying Protocol Stack and is no longer the 2456 responsibility of this interface. The exact disposition of the 2457 Message (i.e., whether it has actually been transmitted, moved into a 2458 buffer on the network interface, moved into a kernel buffer, and so 2459 on) when the Sent Event occurs is implementation-specific. The Sent 2460 Event contains a reference to the Message to which it applies. 2462 Sent Events allow an application to obtain an understanding of the 2463 amount of buffering it creates. That is, if an application calls the 2464 Send Action multiple times without waiting for a Sent Event, it has 2465 created more buffer inside the transport system than an application 2466 that always waits for the Sent Event before calling the next Send 2467 Action. 2469 8.2.3.2. Expired 2471 Connection -> Expired 2473 The Expired Event occurs when a previous Send Action expired before 2474 completion; i.e. when the Message was not sent before its Lifetime 2475 (see Section 8.1.3.1) expired. This is separate from SendError, as 2476 it is an expected behavior for partially reliable transports. The 2477 Expired Event contains a reference to the Message to which it 2478 applies. 2480 8.2.3.3. SendError 2482 Connection -> SendError 2484 A SendError occurs when a Message could not be sent due to an error 2485 condition: an attempt to send a Message which is too large for the 2486 system and Protocol Stack to handle, some failure of the underlying 2487 Protocol Stack, or a set of Message Properties not consistent with 2488 the Connection's transport properties. The SendError contains a 2489 reference to the Message to which it applies. 2491 8.2.4. Partial Sends 2493 It is not always possible for an application to send all data 2494 associated with a Message in a single Send Action. The Message data 2495 may be too large for the application to hold in memory at one time, 2496 or the length of the Message may be unknown or unbounded. 2498 Partial Message sending is supported by passing an endOfMessage 2499 boolean parameter to the Send Action. This value is always true by 2500 default, and the simpler forms of Send are equivalent to passing true 2501 for endOfMessage. 2503 The following example sends a Message in two separate calls to Send. 2505 messageContext := NewMessageContext() 2506 messageContext.add(parameter, value) 2508 messageData := "hel" 2509 endOfMessage := false 2510 Connection.Send(messageData, messageContext, endOfMessage) 2512 messageData := "lo" 2513 endOfMessage := true 2514 Connection.Send(messageData, messageContext, endOfMessage) 2516 All data sent with the same MessageContext object will be treated as 2517 belonging to the same Message, and will constitute an in-order series 2518 until the endOfMessage is marked. 2520 8.2.5. Batching Sends 2522 To reduce the overhead of sending multiple small Messages on a 2523 Connection, the application may want to batch several Send Actions 2524 together. This provides a hint to the system that the sending of 2525 these Messages should be coalesced when possible, and that sending 2526 any of the batched Messages may be delayed until the last Message in 2527 the batch is enqueued. 2529 The semantics for starting and ending a batch can be implementation- 2530 specific, but need to allow multiple Send Actions to be enqueued. 2532 Connection.StartBatch() 2533 Connection.Send(messageData) 2534 Connection.Send(messageData) 2535 Connection.EndBatch() 2537 8.2.6. Send on Active Open: InitiateWithSend 2539 For application-layer protocols where the Connection initiator also 2540 sends the first message, the InitiateWithSend() action combines 2541 Connection initiation with a first Message sent: 2543 Connection := Preconnection.InitiateWithSend(messageData, messageContext?, timeout?) 2545 Whenever possible, a messageContext should be provided to declare the 2546 Message passed to InitiateWithSend as "Safely Replayable". This 2547 allows the transport system to make use of 0-RTT establishment in 2548 case this is supported by the available protocol stacks. When the 2549 selected stack(s) do not support transmitting data upon connection 2550 establishment, InitiateWithSend is identical to Initiate() followed 2551 by Send(). 2553 Neither partial sends nor send batching are supported by 2554 InitiateWithSend(). 2556 The Events that may be sent after InitiateWithSend() are equivalent 2557 to those that would be sent by an invocation of Initiate() followed 2558 immediately by an invocation of Send(), with the caveat that a send 2559 failure that occurs because the Connection could not be established 2560 will not result in a SendError separate from the InitiateError 2561 signaling the failure of Connection establishment. 2563 8.3. Receiving Data 2565 Once a Connection is established, it can be used for receiving data 2566 (unless the "Direction of Communication" property is set to 2567 "unidirectional send"). As with sending, data is received in terms 2568 of Messages. Receiving is an asynchronous operation, in which each 2569 call to Receive enqueues a request to receive new data from the 2570 connection. Once data has been received, or an error is encountered, 2571 an event will be delivered to complete any pending Receive requests 2572 (see Section 8.3.2). If Messages arrive at the transport system 2573 before Receive requests are issued, ensuing Receive requests will 2574 first operate on these Messages before awaiting any further Messages. 2576 8.3.1. Enqueuing Receives 2578 Receive takes two parameters to specify the length of data that an 2579 application is willing to receive, both of which are optional and 2580 have default values if not specified. 2582 Connection.Receive(minIncompleteLength?, maxLength?) 2584 By default, Receive will try to deliver complete Messages in a single 2585 event (Section 8.3.2.1). 2587 The application can set a minIncompleteLength value to indicate the 2588 smallest partial Message data size in bytes that should be delivered 2589 in response to this Receive. By default, this value is infinite, 2590 which means that only complete Messages should be delivered (see 2591 Section 8.3.2.2 and Section 8.1.2 for more information on how this is 2592 accomplished). If this value is set to some smaller value, the 2593 associated receive event will be triggered only when at least that 2594 many bytes are available, or the Message is complete with fewer 2595 bytes, or the system needs to free up memory. Applications should 2596 always check the length of the data delivered to the receive event 2597 and not assume it will be as long as minIncompleteLength in the case 2598 of shorter complete Messages or memory issues. 2600 The maxLength argument indicates the maximum size of a Message in 2601 bytes the application is currently prepared to receive. The default 2602 value for maxLength is infinite. If an incoming Message is larger 2603 than the minimum of this size and the maximum Message size on receive 2604 for the Connection's Protocol Stack, it will be delivered via 2605 ReceivedPartial events (Section 8.3.2.2). 2607 Note that maxLength does not guarantee that the application will 2608 receive that many bytes if they are available; the interface may 2609 return ReceivedPartial events with less data than maxLength according 2610 to implementation constraints. Note also that maxLength and 2611 minIncompleteLength are intended only to manage buffering, and are 2612 not interpreted as a receiver preference for message reordering. 2614 8.3.2. Receive Events 2616 Each call to Receive will be paired with a single Receive Event, 2617 which can be a success or an error. This allows an application to 2618 provide backpressure to the transport stack when it is temporarily 2619 not ready to receive messages. 2621 The interface should allow the application to correlate which call to 2622 Receive resulted in a particular Receive Event. The manner in which 2623 this correlation is indicated is implementation-specific. 2625 8.3.2.1. Received 2627 Connection -> Received 2629 A Received event indicates the delivery of a complete Message. It 2630 contains two objects, the received bytes as messageData, and the 2631 metadata and properties of the received Message as messageContext. 2633 The messageData object provides access to the bytes that were 2634 received for this Message, along with the length of the byte array. 2635 The messageContext is provided to enable retrieving metadata about 2636 the message and referring to the message, e.g., to send replies and 2637 map responses to their requests. See Section 8.1.1 for details. 2639 See Section 8.1.2 for handling Message framing in situations where 2640 the Protocol Stack only provides a byte-stream transport. 2642 8.3.2.2. ReceivedPartial 2644 Connection -> ReceivedPartial 2646 If a complete Message cannot be delivered in one event, one part of 2647 the Message may be delivered with a ReceivedPartial event. In order 2648 to continue to receive more of the same Message, the application must 2649 invoke Receive again. 2651 Multiple invocations of ReceivedPartial deliver data for the same 2652 Message by passing the same MessageContext, until the endOfMessage 2653 flag is delivered or a ReceiveError occurs. All partial blocks of a 2654 single Message are delivered in order without gaps. This event does 2655 not support delivering discontiguous partial Messages. 2657 If the minIncompleteLength in the Receive request was set to be 2658 infinite (indicating a request to receive only complete Messages), 2659 the ReceivedPartial event may still be delivered if one of the 2660 following conditions is true: 2662 o the underlying Protocol Stack supports message boundary 2663 preservation, and the size of the Message is larger than the 2664 buffers available for a single message; 2666 o the underlying Protocol Stack does not support message boundary 2667 preservation, and the Message Framer (see Section 8.1.2) cannot 2668 determine the end of the message using the buffer space it has 2669 available; or 2671 o the underlying Protocol Stack does not support message boundary 2672 preservation, and no Message Framer was supplied by the 2673 application 2675 Note that in the absence of message boundary preservation or a 2676 Message Framer, all bytes received on the Connection will be 2677 represented as one large Message of indeterminate length. 2679 8.3.2.3. ReceiveError 2681 Connection -> ReceiveError 2683 A ReceiveError occurs when data is received by the underlying 2684 Protocol Stack that cannot be fully retrieved or parsed, or when some 2685 other indication is received that reception has failed. In contrast, 2686 conditions that irrevocably lead to the termination of the Connection 2687 are signaled using ConnectionError instead (see Section 9). 2689 The ReceiveError event passes an optional associated MessageContext. 2690 This may indicate that a Message that was being partially received 2691 previously, but had not completed, encountered an error and will not 2692 be completed. 2694 8.3.3. Receive Message Properties 2696 Each Message Context may contain metadata from protocols in the 2697 Protocol Stack; which metadata is available is Protocol Stack 2698 dependent. These are exposed though additional read-only Message 2699 Properties that can be queried from the MessageContext object (see 2700 Section 8.1.1) passed by the receive event. The following metadata 2701 values are supported: 2703 8.3.3.1. UDP(-Lite)-specific Property: ECN 2705 When available, Message metadata carries the value of the Explicit 2706 Congestion Notification (ECN) field. This information can be used 2707 for logging and debugging purposes, and for building applications 2708 which need access to information about the transport internals for 2709 their own operation. This property is specific to UDP and UDP-Lite 2710 because these protocols do not implement congestion control, and 2711 hence expose this functionality to the application. 2713 8.3.3.2. Early Data 2715 In some cases it may be valuable to know whether data was read as 2716 part of early data transfer (before connection establishment has 2717 finished). This is useful if applications need to treat early data 2718 separately, e.g., if early data has different security properties 2719 than data sent after connection establishment. In the case of TLS 2720 1.3, client early data can be replayed maliciously (see [RFC8446]). 2721 Thus, receivers may wish to perform additional checks for early data 2722 to ensure it is safely replayable. If TLS 1.3 is available and the 2723 recipient Message was sent as part of early data, the corresponding 2724 metadata carries a flag indicating as such. If early data is 2725 enabled, applications should check this metadata field for Messages 2726 received during connection establishment and respond accordingly. 2728 8.3.3.3. Receiving Final Messages 2730 The Message Context can indicate whether or not this Message is the 2731 Final Message on a Connection. For any Message that is marked as 2732 Final, the application can assume that there will be no more Messages 2733 received on the Connection once the Message has been completely 2734 delivered. This corresponds to the Final property that may be marked 2735 on a sent Message, see Section 8.1.3.5. 2737 Some transport protocols and peers may not support signaling of the 2738 Final property. Applications therefore should not rely on receiving 2739 a Message marked Final to know that the other endpoint is done 2740 sending on a connection. 2742 Any calls to Receive once the Final Message has been delivered will 2743 result in errors. 2745 9. Connection Termination 2747 Close terminates a Connection after satisfying all the requirements 2748 that were specified regarding the delivery of Messages that the 2749 application has already given to the transport system. For example, 2750 if reliable delivery was requested for a Message handed over before 2751 calling Close, the transport system will ensure that this Message is 2752 indeed delivered. If the Remote Endpoint still has data to send, it 2753 cannot be received after this call. 2755 Connection.Close() 2757 The Closed Event can inform the application that the Remote Endpoint 2758 has closed the Connection; however, there is no guarantee that a 2759 remote Close will indeed be signaled. 2761 Connection -> Closed<> 2763 Abort terminates a Connection without delivering remaining data: 2765 Connection.Abort() 2766 A ConnectionError informs the application that data to could not be 2767 delivered after a timeout, or the other side has aborted the 2768 Connection; however, there is no guarantee that an Abort will indeed 2769 be signaled. 2771 Connection -> ConnectionError 2773 10. Connection State and Ordering of Operations and Events 2775 As this interface is designed to be independent of an 2776 implementation's concurrency model, the details of how exactly 2777 actions are handled, and how events are dispatched, are 2778 implementation dependent. 2780 Each transition of connection state is associated with one of more 2781 events: 2783 o Ready<> occurs when a Connection created with Initiate() or 2784 InitiateWithSend() transitions to Established state. 2786 o ConnectionReceived<> occurs when a Connection created with 2787 Listen() transitions to Established state. 2789 o RendezvousDone<> occurs when a Connection created with 2790 Rendezvous() transitions to Established state. 2792 o Closed<> occurs when a Connection transitions to Closed state 2793 without error. 2795 o InitiateError<> occurs when a Connection created with Initiate() 2796 transitions from Establishing state to Closed state due to an 2797 error. 2799 o ConnectionError<> occurs when a Connection transitions to Closed 2800 state due to an error in all other circumstances. 2802 The following diagram shows the possible states of a Connection and 2803 the events that occur upon a transition from one state to another. 2805 (*) (**) 2806 Establishing -----> Established -----> Closed 2807 | ^ 2808 | | 2809 +-----------------------------------+ 2810 InitiateError<> 2812 (*) Ready<>, ConnectionReceived<>, RendezvousDone<> 2813 (**) Closed<>, ConnectionError<> 2815 Figure 1: Connection State Diagram 2817 The interface provides the following guarantees about the ordering of 2818 operations: 2820 o Sent<> events will occur on a Connection in the order in which the 2821 Messages were sent (i.e., delivered to the kernel or to the 2822 network interface, depending on implementation). 2824 o Received<> will never occur on a Connection before it is 2825 Established; i.e. before a Ready<> event on that Connection, or a 2826 ConnectionReceived<> or RendezvousDone<> containing that 2827 Connection. 2829 o No events will occur on a Connection after it is Closed; i.e., 2830 after a Closed<> event, an InitiateError<> or ConnectionError<> on 2831 that connection. To ensure this ordering, Closed<> will not occur 2832 on a Connection while other events on the Connection are still 2833 locally outstanding (i.e., known to the interface and waiting to 2834 be dealt with by the application). ConnectionError<> may occur 2835 after Closed<>, but the interface must gracefully handle all cases 2836 where application ignores these errors. 2838 11. IANA Considerations 2840 RFC-EDITOR: Please remove this section before publication. 2842 This document has no Actions for IANA. Later versions of this 2843 document may create IANA registries for generic transport property 2844 names and transport property namespaces (see Section 4.2.1). 2846 12. Security Considerations 2848 This document describes a generic API for interacting with a 2849 transport services (TAPS) system. Part of this API includes 2850 configuration details for transport security protocols, as discussed 2851 in Section 5.3. It does not recommend use (or disuse) of specific 2852 algorithms or protocols. Any API-compatible transport security 2853 protocol should work in a TAPS system. Security consideration for 2854 these protocols should be discussed in the respective specifications. 2856 The desribed API is used to exchange information between an 2857 application and the transport system. While it is not necessarily 2858 expected that both systems are implemented by the same authority, it 2859 is expected that the transport system implementation is either 2860 provided as a library that is selected by the application from a 2861 trusted party, or that it is part of the operating system that the 2862 application also relies on for other tasks. 2864 In either case, the TAPS API is an internal interface that is used to 2865 change information locally between two systems. However, as the 2866 transport system is responsible for network communication, it is in 2867 the position to potentially share any information provided by the 2868 application with the network or another communication peer. Most of 2869 the information provided over the TAPS API are useful to configure 2870 and select protocols and paths and are not necessarily privacy 2871 sensitive. Still, there is some information that could be privacy 2872 sensitve because this might reveal usage characteristics and habits 2873 of the user of an application. 2875 Of course any communication over a network reveals usage 2876 characteristics, as all packets as well as their timing and size are 2877 part of the network-visible wire image [RFC8546]. However, the 2878 selection of a protocol and its configuration also impacts which 2879 information is visible, potentially in clear text, and which other 2880 enties can access it. In most cases information that is provided for 2881 protocol and path selection should not directly translate to 2882 information that is can be observed by network devices on the path. 2883 But there might be specific configuration information that are 2884 intended for path exposure, such as e.g. a DiffServ codepoint 2885 setting, that is either povided directly by the application or 2886 indirectly configured over a traffic profile. 2888 Further, applications should be aware that communication attempts can 2889 lead to more than one connection establishment. This is for example 2890 the case when the transport system also excecutes name resolution; or 2891 when support mechanisms such as TURN or ICE are used to establish 2892 connectivity; or if protocols or paths are raised; or if a path fails 2893 and fallback or re-establishment is supported in the transport 2894 system. 2896 These communication activities are not different from what is used 2897 today, however, the goal of a TAPS transport system is to support 2898 such mechanisms as a generic service within the transport layer. 2899 This enables applications to more dynamically benefit from 2900 innovations and new protocols in the transport system but at the same 2901 time may reduce transparency of the underlying communication actions 2902 to the application itself. The TAPS API is designed such that 2903 protocol and path selection can be limited to a small and controlled 2904 set if required by the application for functional or security 2905 purposes. Further, TAPS implementations should provide an interface 2906 to poll information about which protocol and path is currently in use 2907 as well as provide logging about the communication events of each 2908 connection. 2910 13. Acknowledgements 2912 This work has received funding from the European Union's Horizon 2020 2913 research and innovation programme under grant agreements No. 644334 2914 (NEAT) and No. 688421 (MAMI). 2916 This work has been supported by Leibniz Prize project funds of DFG - 2917 German Research Foundation: Gottfried Wilhelm Leibniz-Preis 2011 (FKZ 2918 FE 570/4-1). 2920 This work has been supported by the UK Engineering and Physical 2921 Sciences Research Council under grant EP/R04144X/1. 2923 This work has been supported by the Research Council of Norway under 2924 its "Toppforsk" programme through the "OCARINA" project. 2926 Thanks to Stuart Cheshire, Josh Graessley, David Schinazi, and Eric 2927 Kinnear for their implementation and design efforts, including Happy 2928 Eyeballs, that heavily influenced this work. Thanks to Laurent Chuat 2929 and Jason Lee for initial work on the Post Sockets interface, from 2930 which this work has evolved. Thanks to Maximilian Franke for asking 2931 good questions based on implementation experience and for 2932 contributing text, e.g., on multicast. 2934 14. References 2936 14.1. Normative References 2938 [I-D.ietf-taps-arch] 2939 Pauly, T., Trammell, B., Brunstrom, A., Fairhurst, G., 2940 Perkins, C., Tiesel, P., and C. Wood, "An Architecture for 2941 Transport Services", draft-ietf-taps-arch-08 (work in 2942 progress), July 2020. 2944 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2945 Requirement Levels", BCP 14, RFC 2119, 2946 DOI 10.17487/RFC2119, March 1997, 2947 . 2949 [RFC4941] Narten, T., Draves, R., and S. Krishnan, "Privacy 2950 Extensions for Stateless Address Autoconfiguration in 2951 IPv6", RFC 4941, DOI 10.17487/RFC4941, September 2007, 2952 . 2954 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2955 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2956 May 2017, . 2958 [RFC8303] Welzl, M., Tuexen, M., and N. Khademi, "On the Usage of 2959 Transport Features Provided by IETF Transport Protocols", 2960 RFC 8303, DOI 10.17487/RFC8303, February 2018, 2961 . 2963 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2964 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2965 . 2967 14.2. Informative References 2969 [I-D.ietf-taps-impl] 2970 Brunstrom, A., Pauly, T., Enghardt, T., Grinnemo, K., 2971 Jones, T., Tiesel, P., Perkins, C., and M. Welzl, 2972 "Implementing Interfaces to Transport Services", draft- 2973 ietf-taps-impl-07 (work in progress), July 2020. 2975 [I-D.ietf-taps-minset] 2976 Welzl, M. and S. Gjessing, "A Minimal Set of Transport 2977 Services for End Systems", draft-ietf-taps-minset-11 (work 2978 in progress), September 2018. 2980 [I-D.ietf-taps-transport-security] 2981 Enghardt, T., Pauly, T., Perkins, C., Rose, K., and C. 2982 Wood, "A Survey of the Interaction Between Security 2983 Protocols and Transport Services", draft-ietf-taps- 2984 transport-security-12 (work in progress), April 2020. 2986 [I-D.ietf-tsvwg-datagram-plpmtud] 2987 Fairhurst, G., Jones, T., Tuexen, M., Ruengeler, I., and 2988 T. Voelker, "Packetization Layer Path MTU Discovery for 2989 Datagram Transports", draft-ietf-tsvwg-datagram-plpmtud-22 2990 (work in progress), June 2020. 2992 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 2993 "Definition of the Differentiated Services Field (DS 2994 Field) in the IPv4 and IPv6 Headers", RFC 2474, 2995 DOI 10.17487/RFC2474, December 1998, 2996 . 2998 [RFC2597] Heinanen, J., Baker, F., Weiss, W., and J. Wroclawski, 2999 "Assured Forwarding PHB Group", RFC 2597, 3000 DOI 10.17487/RFC2597, June 1999, 3001 . 3003 [RFC2914] Floyd, S., "Congestion Control Principles", BCP 41, 3004 RFC 2914, DOI 10.17487/RFC2914, September 2000, 3005 . 3007 [RFC3246] Davie, B., Charny, A., Bennet, J., Benson, K., Le Boudec, 3008 J., Courtney, W., Davari, S., Firoiu, V., and D. 3009 Stiliadis, "An Expedited Forwarding PHB (Per-Hop 3010 Behavior)", RFC 3246, DOI 10.17487/RFC3246, March 2002, 3011 . 3013 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 3014 A., Peterson, J., Sparks, R., Handley, M., and E. 3015 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 3016 DOI 10.17487/RFC3261, June 2002, 3017 . 3019 [RFC4594] Babiarz, J., Chan, K., and F. Baker, "Configuration 3020 Guidelines for DiffServ Service Classes", RFC 4594, 3021 DOI 10.17487/RFC4594, August 2006, 3022 . 3024 [RFC5245] Rosenberg, J., "Interactive Connectivity Establishment 3025 (ICE): A Protocol for Network Address Translator (NAT) 3026 Traversal for Offer/Answer Protocols", RFC 5245, 3027 DOI 10.17487/RFC5245, April 2010, 3028 . 3030 [RFC5482] Eggert, L. and F. Gont, "TCP User Timeout Option", 3031 RFC 5482, DOI 10.17487/RFC5482, March 2009, 3032 . 3034 [RFC5865] Baker, F., Polk, J., and M. Dolly, "A Differentiated 3035 Services Code Point (DSCP) for Capacity-Admitted Traffic", 3036 RFC 5865, DOI 10.17487/RFC5865, May 2010, 3037 . 3039 [RFC7478] Holmberg, C., Hakansson, S., and G. Eriksson, "Web Real- 3040 Time Communication Use Cases and Requirements", RFC 7478, 3041 DOI 10.17487/RFC7478, March 2015, 3042 . 3044 [RFC7556] Anipko, D., Ed., "Multiple Provisioning Domain 3045 Architecture", RFC 7556, DOI 10.17487/RFC7556, June 2015, 3046 . 3048 [RFC7657] Black, D., Ed. and P. Jones, "Differentiated Services 3049 (Diffserv) and Real-Time Communication", RFC 7657, 3050 DOI 10.17487/RFC7657, November 2015, 3051 . 3053 [RFC8084] Fairhurst, G., "Network Transport Circuit Breakers", 3054 BCP 208, RFC 8084, DOI 10.17487/RFC8084, March 2017, 3055 . 3057 [RFC8095] Fairhurst, G., Ed., Trammell, B., Ed., and M. Kuehlewind, 3058 Ed., "Services Provided by IETF Transport Protocols and 3059 Congestion Control Mechanisms", RFC 8095, 3060 DOI 10.17487/RFC8095, March 2017, 3061 . 3063 [RFC8229] Pauly, T., Touati, S., and R. Mantha, "TCP Encapsulation 3064 of IKE and IPsec Packets", RFC 8229, DOI 10.17487/RFC8229, 3065 August 2017, . 3067 [RFC8260] Stewart, R., Tuexen, M., Loreto, S., and R. Seggelmann, 3068 "Stream Schedulers and User Message Interleaving for the 3069 Stream Control Transmission Protocol", RFC 8260, 3070 DOI 10.17487/RFC8260, November 2017, 3071 . 3073 [RFC8546] Trammell, B. and M. Kuehlewind, "The Wire Image of a 3074 Network Protocol", RFC 8546, DOI 10.17487/RFC8546, April 3075 2019, . 3077 [RFC8622] Bless, R., "A Lower-Effort Per-Hop Behavior (LE PHB) for 3078 Differentiated Services", RFC 8622, DOI 10.17487/RFC8622, 3079 June 2019, . 3081 [RFC8699] Islam, S., Welzl, M., and S. Gjessing, "Coupled Congestion 3082 Control for RTP Media", RFC 8699, DOI 10.17487/RFC8699, 3083 January 2020, . 3085 [TCP-COUPLING] 3086 "ctrlTCP: Reducing Latency through Coupled, Heterogeneous 3087 Multi-Flow TCP Congestion Control", IEEE INFOCOM Global 3088 Internet Symposium (GI) workshop (GI 2018) , April 2018. 3090 Appendix A. Convenience Functions 3092 A.1. Adding Preference Properties 3094 As Selection Properties of type "Preference" will be added to a 3095 TransportProperties object quite frequently, implementations should 3096 provide special actions for adding each preference level i.e, 3097 "TransportProperties.Add(some_property, avoid)" is equivalent to 3098 "TransportProperties.Avoid(some_property)": 3100 TransportProperties.Require(property) 3101 TransportProperties.Prefer(property) 3102 TransportProperties.Ignore(property) 3103 TransportProperties.Avoid(property) 3104 TransportProperties.Prohibit(property) 3105 TransportProperties.Default(property) 3107 A.2. Transport Property Profiles 3109 To ease the use of the interface specified by this document, 3110 implementations should provide a mechanism to create Transport 3111 Property objects (see Section 5.2) that are pre-configured with 3112 frequently used sets of properties. Implementations should at least 3113 offer short-hands to specify the following property profiles: 3115 A.2.1. reliable-inorder-stream 3117 This profile provides reliable, in-order transport service with 3118 congestion control. An example of a protocol that provides this 3119 service is TCP. It should consist of the following properties: 3121 +-----------------------+---------+ 3122 | Property | Value | 3123 +-----------------------+---------+ 3124 | reliability | require | 3125 | | | 3126 | preserveOrder | require | 3127 | | | 3128 | congestionControl | require | 3129 | | | 3130 | preserveMsgBoundaries | ignore | 3131 +-----------------------+---------+ 3133 A.2.2. reliable-message 3135 This profile provides message-preserving, reliable, in-order 3136 transport service with congestion control. An example of a protocol 3137 that provides this service is SCTP. It should consist of the 3138 following properties: 3140 +-----------------------+---------+ 3141 | Property | Value | 3142 +-----------------------+---------+ 3143 | reliability | require | 3144 | | | 3145 | preserveOrder | require | 3146 | | | 3147 | congestionControl | require | 3148 | | | 3149 | preserveMsgBoundaries | require | 3150 +-----------------------+---------+ 3152 A.2.3. unreliable-datagram 3154 This profile provides unreliable datagram transport service. An 3155 example of a protocol that provides this service is UDP. It should 3156 consist of the following properties: 3158 +-----------------------+---------+ 3159 | Property | Value | 3160 +-----------------------+---------+ 3161 | reliability | ignore | 3162 | | | 3163 | preserveOrder | ignore | 3164 | | | 3165 | congestionControl | ignore | 3166 | | | 3167 | preserveMsgBoundaries | require | 3168 | | | 3169 | safely replayable | true | 3170 +-----------------------+---------+ 3172 Applications that choose this Transport Property Profile for latency 3173 reasons should also consider setting the Capacity Profile Property, 3174 see Section 7.1.6 accordingly and my benefit from controlling 3175 checksum coverage, see Section 5.2.7 and Section 5.2.8. 3177 Appendix B. Relationship to the Minimal Set of Transport Services for 3178 End Systems 3180 [I-D.ietf-taps-minset] identifies a minimal set of transport services 3181 that end systems should offer. These services make all non-security- 3182 related transport features of TCP, MPTCP, UDP, UDP-Lite, SCTP and 3183 LEDBAT available that 1) require interaction with the application, 3184 and 2) do not get in the way of a possible implementation over TCP 3185 (or, with limitations, UDP). The following text explains how this 3186 minimal set is reflected in the present API. For brevity, it is 3187 based on the list in Section 4.1 of [I-D.ietf-taps-minset], updated 3188 according to the discussion in Section 5 of [I-D.ietf-taps-minset]. 3189 This list is a subset of the transport features in Appendix A of 3190 [I-D.ietf-taps-minset], which refers to the primitives in "pass 2" 3191 (Section 4) of [RFC8303] for further details on the implementation 3192 with TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT. 3194 o Connect: "Initiate" Action (Section 6.1). 3196 o Listen: "Listen" Action (Section 6.2). 3198 o Specify number of attempts and/or timeout for the first 3199 establishment message: "timeout" parameter of "Initiate" 3200 (Section 6.1) or "InitiateWithSend" Action (Section 8.2.6). 3202 o Disable MPTCP: "Parallel Use of Multiple Paths" Property 3203 (Section 5.2.13). 3205 o Hand over a message to reliably transfer (possibly multiple times) 3206 before connection establishment: "InitiateWithSend" Action 3207 (Section 8.2.6). 3209 o Change timeout for aborting connection (using retransmit limit or 3210 time value): "Timeout for Aborting Connection" property, using a 3211 time value (Section 7.1.4). 3213 o Timeout event when data could not be delivered for too long: 3214 "ConnectionError" Event (Section 9). 3216 o Suggest timeout to the peer: "TCP-specific Property: User Timeout" 3217 (Section 7.2). 3219 o Notification of Excessive Retransmissions (early warning below 3220 abortion threshold): "Notification of excessive retransmissions" 3221 property (Section 5.2.16). 3223 o Notification of ICMP error message arrival: "Notification of ICMP 3224 soft error message arrival" property (Section 5.2.17). 3226 o Choose a scheduler to operate between streams of an association: 3227 "Connection Group Transmission Scheduler" property 3228 (Section 7.1.5). 3230 o Configure priority or weight for a scheduler: "Priority 3231 (Connection)" property (Section 7.1.3). 3233 o "Specify checksum coverage used by the sender" and "Disable 3234 checksum when sending": "Corruption Protection Length" property 3235 (Section 8.1.3.6) and "Full Checksum Coverage on Sending" property 3236 (Section 5.2.7). 3238 o "Specify minimum checksum coverage required by receiver" and 3239 "Disable checksum requirement when receiving": "Required Minimum 3240 Corruption Protection Coverage for Receiving" property 3241 (Section 7.1.2) and "Full Checksum Coverage on Receiving" property 3242 (Section 5.2.8). 3244 o "Specify DF" field and "Request not to bundle messages": the "No 3245 Fragmentation" Message Property combines both of these requests, 3246 i.e. if a request not to bundle messages is made, this also turns 3247 off fragmentation (i.e., sets DF=1) in the case of a protocol that 3248 allows this (only UDP and UDP-Lite, which cannot bundle messages 3249 anyway) (Section 8.1.3.9). 3251 o Get max. transport-message size that may be sent using a non- 3252 fragmented IP packet from the configured interface: "Maximum 3253 Message Size Before Fragmentation or Segmentation" property 3254 (Section 7.1.9.2). 3256 o Get max. transport-message size that may be received from the 3257 configured interface: "Maximum Message Size on Receive" property 3258 (Section 7.1.9.4). 3260 o Obtain ECN field: "ECN" is a defined UDP(-Lite)-specific read-only 3261 Message Property of the MessageContext object (Section 8.3.3.1). 3263 o "Specify DSCP field", "Disable Nagle algorithm", "Enable and 3264 configure a "Low Extra Delay Background Transfer"": as suggested 3265 in Section 5.5 of [I-D.ietf-taps-minset], these transport features 3266 are collectively offered via the "Capacity Profile" property 3267 (Section 7.1.6). Per-Message control is offered via the "Message 3268 Capacity Profile Override" property (Section 8.1.3.8). 3270 o Close after reliably delivering all remaining data, causing an 3271 event informing the application on the other side: this is offered 3272 by the "Close" Action with slightly changed semantics in line with 3273 the discussion in Section 5.2 of [I-D.ietf-taps-minset] 3274 (Section 9). 3276 o "Abort without delivering remaining data, causing an event 3277 informing the application on the other side" and "Abort without 3278 delivering remaining data, not causing an event informing the 3279 application on the other side": this is offered by the "Abort" 3280 action without promising that this is signaled to the other side. 3282 If it is, a "ConnectionError" Event will fire at the peer 3283 (Section 9). 3285 o "Reliably transfer data, with congestion control", "Reliably 3286 transfer a message, with congestion control" and "Unreliably 3287 transfer a message": data is transferred via the "Send" action 3288 (Section 8.2). Reliability is controlled via the "Reliable Data 3289 Transfer (Connection)" (Section 5.2.1) property and the "Reliable 3290 Data Transfer (Message)" Message Property (Section 8.1.3.7). 3291 Transmitting data as a message or without delimiters is controlled 3292 via Message Framers (Section 8.1.2). The choice of congestion 3293 control is provided via the "Congestion control" property 3294 (Section 5.2.9). 3296 o Configurable Message Reliability: the "Lifetime" Message Property 3297 implements a time-based way to configure message reliability 3298 (Section 8.1.3.1). 3300 o "Ordered message delivery (potentially slower than unordered)" and 3301 "Unordered message delivery (potentially faster than ordered)": 3302 these two transport features are controlled via the Message 3303 Property "Ordered" (Section 8.1.3.3). 3305 o Request not to delay the acknowledgement (SACK) of a message: 3306 should the protocol support it, this is one of the transport 3307 features the transport system can apply when an application uses 3308 the "Capacity Profile" Property (Section 7.1.6) or the "Message 3309 Capacity Profile Override" Message Property (Section 8.1.3.8) with 3310 value "Low Latency/Interactive". 3312 o Receive data (with no message delimiting): "Received" Event 3313 (Section 8.3.2.1). See Section 8.1.2 for handling Message framing 3314 in situations where the Protocol Stack only provides a byte-stream 3315 transport. 3317 o Receive a message: "Received" Event (Section 8.3.2.1), using 3318 Message Framers (Section 8.1.2). 3320 o Information about partial message arrival: "ReceivedPartial" Event 3321 (Section 8.3.2.2). 3323 o Notification of send failures: "Expired" Event (Section 8.2.3.2) 3324 and "SendError" Event (Section 8.2.3.3). 3326 o Notification that the stack has no more user data to send: 3327 applications can obtain this information via the "Sent" Event 3328 (Section 8.2.3.1). 3330 o Notification to a receiver that a partial message delivery has 3331 been aborted: "ReceiveError" Event (Section 8.3.2.3). 3333 Authors' Addresses 3335 Brian Trammell (editor) 3336 Google Switzerland GmbH 3337 Gustav-Gull-Platz 1 3338 8004 Zurich 3339 Switzerland 3341 Email: ietf@trammell.ch 3343 Michael Welzl (editor) 3344 University of Oslo 3345 PO Box 1080 Blindern 3346 0316 Oslo 3347 Norway 3349 Email: michawe@ifi.uio.no 3351 Theresa Enghardt 3352 Netflix 3353 121 Albright Way 3354 Los Gatos, CA 95032 3355 United States of America 3357 Email: ietf@tenghardt.net 3359 Godred Fairhurst 3360 University of Aberdeen 3361 Fraser Noble Building 3362 Aberdeen, AB24 3UE 3363 Scotland 3365 Email: gorry@erg.abdn.ac.uk 3366 URI: http://www.erg.abdn.ac.uk/ 3367 Mirja Kuehlewind 3368 Ericsson 3369 Ericsson-Allee 1 3370 Herzogenrath 3371 Germany 3373 Email: mirja.kuehlewind@ericsson.com 3375 Colin Perkins 3376 University of Glasgow 3377 School of Computing Science 3378 Glasgow G12 8QQ 3379 United Kingdom 3381 Email: csp@csperkins.org 3383 Philipp S. Tiesel 3384 TU Berlin 3385 Einsteinufer 25 3386 10587 Berlin 3387 Germany 3389 Email: philipp@tiesel.net 3391 Christopher A. Wood 3392 Cloudflare 3393 101 Townsend St 3394 San Francisco 3395 United States of America 3397 Email: caw@heapingbits.net 3399 Tommy Pauly 3400 Apple Inc. 3401 One Apple Park Way 3402 Cupertino, California 95014 3403 United States of America 3405 Email: tpauly@apple.com