idnits 2.17.1 draft-ietf-taps-interface-06.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 3 instances of too long lines in the document, the longest one being 15 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 the keywords provided in the IANA protocol numbers registry (see https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml) are reserved for Protocol Specific Properties and MUST not be used for vendor or implementation specific properties. -- The document date (9 March 2020) is 1502 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-06 ** 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-05 == Outdated reference: A later version (-12) exists of draft-ietf-taps-transport-security-11 == Outdated reference: A later version (-22) exists of draft-ietf-tsvwg-datagram-plpmtud-15 -- Obsolete informational reference (is this intentional?): RFC 5245 (Obsoleted by RFC 8445, RFC 8839) Summary: 3 errors (**), 0 flaws (~~), 6 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 TAPS Working Group B. Trammell, Ed. 3 Internet-Draft Google 4 Intended status: Standards Track M. Welzl, Ed. 5 Expires: 10 September 2020 University of Oslo 6 T. Enghardt 7 TU Berlin 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 T. Pauly 18 Apple Inc. 19 9 March 2020 21 An Abstract Application Layer Interface to Transport Services 22 draft-ietf-taps-interface-06 24 Abstract 26 This document describes an abstract programming interface to the 27 transport layer, following the Transport Services Architecture. It 28 supports the asynchronous, atomic transmission of messages over 29 transport protocols and network paths dynamically selected at 30 runtime. It is intended to replace the traditional BSD sockets API 31 as the lowest common denominator interface to the transport layer, in 32 an environment where endpoints have multiple interfaces and potential 33 transport protocols to select from. 35 Status of This Memo 37 This Internet-Draft is submitted in full conformance with the 38 provisions of BCP 78 and BCP 79. 40 Internet-Drafts are working documents of the Internet Engineering 41 Task Force (IETF). Note that other groups may also distribute 42 working documents as Internet-Drafts. The list of current Internet- 43 Drafts is at https://datatracker.ietf.org/drafts/current/. 45 Internet-Drafts are draft documents valid for a maximum of six months 46 and may be updated, replaced, or obsoleted by other documents at any 47 time. It is inappropriate to use Internet-Drafts as reference 48 material or to cite them other than as "work in progress." 49 This Internet-Draft will expire on 10 September 2020. 51 Copyright Notice 53 Copyright (c) 2020 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 58 license-info) in effect on the date of publication of this document. 59 Please review these documents carefully, as they describe your rights 60 and restrictions with respect to this document. Code Components 61 extracted from this document must include Simplified BSD License text 62 as described in Section 4.e of the Trust Legal Provisions and are 63 provided without warranty as described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 68 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 5 69 3. Overview of Interface Design . . . . . . . . . . . . . . . . 6 70 4. API Summary . . . . . . . . . . . . . . . . . . . . . . . . . 7 71 4.1. Usage Examples . . . . . . . . . . . . . . . . . . . . . 8 72 4.1.1. Server Example . . . . . . . . . . . . . . . . . . . 8 73 4.1.2. Client Example . . . . . . . . . . . . . . . . . . . 9 74 4.1.3. Peer Example . . . . . . . . . . . . . . . . . . . . 10 75 4.2. Transport Properties . . . . . . . . . . . . . . . . . . 11 76 4.2.1. Transport Property Names . . . . . . . . . . . . . . 12 77 4.2.2. Transport Property Types . . . . . . . . . . . . . . 13 78 4.3. Scope of the Interface Definition . . . . . . . . . . . . 13 79 5. Pre-Establishment Phase . . . . . . . . . . . . . . . . . . . 14 80 5.1. Specifying Endpoints . . . . . . . . . . . . . . . . . . 15 81 5.2. Specifying Transport Properties . . . . . . . . . . . . . 17 82 5.2.1. Reliable Data Transfer (Connection) . . . . . . . . . 19 83 5.2.2. Preservation of Message Boundaries . . . . . . . . . 20 84 5.2.3. Configure Per-Message Reliability . . . . . . . . . . 20 85 5.2.4. Preservation of Data Ordering . . . . . . . . . . . . 20 86 5.2.5. Use 0-RTT Session Establishment with an Idempotent 87 Message . . . . . . . . . . . . . . . . . . . . . . . 20 88 5.2.6. Multistream Connections in Group . . . . . . . . . . 21 89 5.2.7. Full Checksum Coverage on Sending . . . . . . . . . . 21 90 5.2.8. Full Checksum Coverage on Receiving . . . . . . . . . 21 91 5.2.9. Congestion control . . . . . . . . . . . . . . . . . 22 92 5.2.10. Interface Instance or Type . . . . . . . . . . . . . 22 93 5.2.11. Provisioning Domain Instance or Type . . . . . . . . 23 94 5.2.12. Use Temporary Local Address . . . . . . . . . . . . . 24 95 5.2.13. Parallel Use of Multiple Paths . . . . . . . . . . . 24 96 5.2.14. Direction of communication . . . . . . . . . . . . . 25 97 5.2.15. Notification of excessive retransmissions . . . . . . 25 98 5.2.16. Notification of ICMP soft error message arrival . . . 25 99 5.3. Specifying Security Parameters and Callbacks . . . . . . 26 100 5.3.1. Pre-Connection Parameters . . . . . . . . . . . . . . 26 101 5.3.2. Connection Establishment Callbacks . . . . . . . . . 27 102 6. Establishing Connections . . . . . . . . . . . . . . . . . . 28 103 6.1. Active Open: Initiate . . . . . . . . . . . . . . . . . . 28 104 6.2. Passive Open: Listen . . . . . . . . . . . . . . . . . . 29 105 6.3. Peer-to-Peer Establishment: Rendezvous . . . . . . . . . 30 106 6.4. Connection Groups . . . . . . . . . . . . . . . . . . . . 32 107 7. Sending Data . . . . . . . . . . . . . . . . . . . . . . . . 33 108 7.1. Basic Sending . . . . . . . . . . . . . . . . . . . . . . 34 109 7.2. Sending Replies . . . . . . . . . . . . . . . . . . . . . 34 110 7.3. Send Events . . . . . . . . . . . . . . . . . . . . . . . 35 111 7.3.1. Sent . . . . . . . . . . . . . . . . . . . . . . . . 35 112 7.3.2. Expired . . . . . . . . . . . . . . . . . . . . . . . 35 113 7.3.3. SendError . . . . . . . . . . . . . . . . . . . . . . 35 114 7.4. Message Contexts . . . . . . . . . . . . . . . . . . . . 36 115 7.5. Message Properties . . . . . . . . . . . . . . . . . . . 36 116 7.5.1. Lifetime . . . . . . . . . . . . . . . . . . . . . . 37 117 7.5.2. Priority . . . . . . . . . . . . . . . . . . . . . . 38 118 7.5.3. Ordered . . . . . . . . . . . . . . . . . . . . . . . 38 119 7.5.4. Idempotent . . . . . . . . . . . . . . . . . . . . . 39 120 7.5.5. Final . . . . . . . . . . . . . . . . . . . . . . . . 39 121 7.5.6. Corruption Protection Length . . . . . . . . . . . . 40 122 7.5.7. Reliable Data Transfer (Message) . . . . . . . . . . 40 123 7.5.8. Message Capacity Profile Override . . . . . . . . . . 40 124 7.5.9. Singular Transmission . . . . . . . . . . . . . . . . 40 125 7.6. Partial Sends . . . . . . . . . . . . . . . . . . . . . . 41 126 7.7. Batching Sends . . . . . . . . . . . . . . . . . . . . . 42 127 7.8. Send on Active Open: InitiateWithSend . . . . . . . . . . 42 128 8. Receiving Data . . . . . . . . . . . . . . . . . . . . . . . 42 129 8.1. Enqueuing Receives . . . . . . . . . . . . . . . . . . . 43 130 8.2. Receive Events . . . . . . . . . . . . . . . . . . . . . 43 131 8.2.1. Received . . . . . . . . . . . . . . . . . . . . . . 44 132 8.2.2. ReceivedPartial . . . . . . . . . . . . . . . . . . . 44 133 8.2.3. ReceiveError . . . . . . . . . . . . . . . . . . . . 45 134 8.3. Receive Message Properties . . . . . . . . . . . . . . . 45 135 8.3.1. UDP(-Lite)-specific Property: ECN . . . . . . . . . . 45 136 8.3.2. Early Data . . . . . . . . . . . . . . . . . . . . . 45 137 8.3.3. Receiving Final Messages . . . . . . . . . . . . . . 46 138 9. Message Framers . . . . . . . . . . . . . . . . . . . . . . . 46 139 9.1. Adding Message Framers to Connections . . . . . . . . . . 47 140 9.2. Framing Meta-Data . . . . . . . . . . . . . . . . . . . . 47 141 10. Managing Connections . . . . . . . . . . . . . . . . . . . . 48 142 10.1. Generic Connection Properties . . . . . . . . . . . . . 49 143 10.1.1. Retransmission Threshold Before Excessive 144 Retransmission Notification . . . . . . . . . . . . . 49 146 10.1.2. Required Minimum Corruption Protection Coverage for 147 Receiving . . . . . . . . . . . . . . . . . . . . . . 50 148 10.1.3. Priority (Connection) . . . . . . . . . . . . . . . 50 149 10.1.4. Timeout for Aborting Connection . . . . . . . . . . 50 150 10.1.5. Connection Group Transmission Scheduler . . . . . . 51 151 10.1.6. Capacity Profile . . . . . . . . . . . . . . . . . . 51 152 10.1.7. Bounds on Send or Receive Rate . . . . . . . . . . . 52 153 10.1.8. Read-only Connection Properties . . . . . . . . . . 53 154 10.2. TCP-specific Properties: User Timeout Option (UTO) . . . 54 155 10.2.1. Advertised User Timeout . . . . . . . . . . . . . . 54 156 10.2.2. User Timeout Enabled . . . . . . . . . . . . . . . . 54 157 10.2.3. Timeout Changeable . . . . . . . . . . . . . . . . . 55 158 10.3. Connection Lifecycle Events . . . . . . . . . . . . . . 55 159 10.3.1. Soft Errors . . . . . . . . . . . . . . . . . . . . 55 160 10.3.2. Excessive retransmissions . . . . . . . . . . . . . 55 161 11. Connection Termination . . . . . . . . . . . . . . . . . . . 55 162 12. Connection State and Ordering of Operations and Events . . . 56 163 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 57 164 14. Security Considerations . . . . . . . . . . . . . . . . . . . 57 165 15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 59 166 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 59 167 16.1. Normative References . . . . . . . . . . . . . . . . . . 59 168 16.2. Informative References . . . . . . . . . . . . . . . . . 60 169 Appendix A. Convenience Functions . . . . . . . . . . . . . . . 62 170 A.1. Adding Preference Properties . . . . . . . . . . . . . . 63 171 A.2. Transport Property Profiles . . . . . . . . . . . . . . . 63 172 A.2.1. reliable-inorder-stream . . . . . . . . . . . . . . . 63 173 A.2.2. reliable-message . . . . . . . . . . . . . . . . . . 64 174 A.2.3. unreliable-datagram . . . . . . . . . . . . . . . . . 64 175 Appendix B. Relationship to the Minimal Set of Transport Services 176 for End Systems . . . . . . . . . . . . . . . . . . . . . 65 177 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 68 179 1. Introduction 181 This document specifies a modern abstract programming interface atop 182 the high-level architecture for transport services defined in 183 [I-D.ietf-taps-arch]. It supports the asynchronous, atomic 184 transmission of messages over transport protocols and network paths 185 dynamically selected at runtime. It is intended to replace the 186 traditional BSD sockets API as the lowest common denominator 187 interface to the transport layer, in an environment where endpoints 188 have multiple interfaces and potential transport protocols to select 189 from. 191 As applications adopt this interface, they will benefit from a wide 192 set of transport features that can evolve over time, and ensure that 193 the system providing the interface can optimize its behavior based on 194 the application requirements and network conditions, without 195 requiring changes to the applications. This flexibility enables 196 faster deployment of new features and protocols. It can also support 197 applications by offering racing and fallback mechanisms, which 198 otherwise need to be implemented in each application separately. 200 It derives specific path and protocol selection properties and 201 supported transport features from the analysis provided in [RFC8095], 202 [I-D.ietf-taps-minset], and [I-D.ietf-taps-transport-security]. The 203 design encourages implementations underneath the interface to 204 dynamically choose a transport protocol depending on an application's 205 choices rather than statically binding applications to a protocol at 206 compile time. We note that transport system implementations SHOULD 207 provide applications a way to override transport selection and 208 instantiate a specific stack, e.g. to support servers wanting to 209 listen to a specific protocol. This specific transport stack choice 210 is discouraged for general use, as it comes at the cost of reduced 211 portability. 213 2. Terminology and Notation 215 This API is described in terms of Objects, which an application can 216 interact with; Actions the application can perform on these Objects; 217 Events, which an Object can send to an application asynchronously; 218 and Parameters associated with these Actions and Events. 220 The following notations, which can be combined, are used in this 221 document: 223 * An Action creates an Object: 225 Object := Action() 227 * An Action creates an array of Objects: 229 []Object := Action() 231 * An Action is performed on an Object: 233 Object.Action() 235 * An Object sends an Event: 237 Object -> Event<> 239 * An Action takes a set of Parameters; an Event contains a set of 240 Parameters. Action and Event parameters whose names are suffixed 241 with a question mark are optional. 243 Action(param0, param1?, ...) / Event 245 Actions associated with no Object are Actions on the abstract 246 interface itself; they are equivalent to Actions on a per-application 247 global context. 249 How these abstract concepts map into concrete implementations of this 250 API in a given language on a given platform is largely dependent on 251 the features of the language and the platform. Actions could be 252 implemented as functions or method calls, for instance, and Events 253 could be implemented via event queues, handler functions or classes, 254 communicating sequential processes, or other asynchronous calling 255 conventions. 257 This specification treats Events and errors similarly. Errors, just 258 as any other Events, may occur asynchronously in network 259 applications. However, it is recommended that implementations of 260 this interface also return errors immediately, according to the error 261 handling idioms of the implementation platform, for errors that can 262 be immediately detected, such as inconsistency in Transport 263 Properties. Errors can provide an optional reason to give the 264 application further details as to why the error occured. 266 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 267 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 268 "OPTIONAL" in this document are to be interpreted as described in BCP 269 14 [RFC2119] [RFC8174] when, and only when, they appear in all 270 capitals, as shown here. 272 3. Overview of Interface Design 274 The design of the interface specified in this document is based on a 275 set of princples, themselves an elaboration on the architectural 276 design principles defined in [I-D.ietf-taps-arch]. The interface 277 defined in this document provides: 279 * A single interface to a variety of transport protocols to be used 280 in a variety of application design patterns, independent of the 281 properties of the application and the Protocol Stacks that will be 282 used at runtime, such that all common specialized features of 283 these protocol stacks are made available to the application as 284 necessary in a transport-independent way, to enable applications 285 written to a single API to make use of transport protocols in 286 terms of the features they provide; 288 * Message-orientation, as opposed to stream-orientation, using 289 application-assisted framing and deframing where the underlying 290 transport does not provide these; 292 * Asynchronous Connection establishment, transmission, and 293 reception, allowing concurrent operations during establishment and 294 supporting event-driven application interactions with the 295 transport layer, in line with developments in modern platforms and 296 programming languages; 298 * Explicit support for security properties as first-order transport 299 features, and for configuration of cryptographic identities and 300 transport security parameters persistent across multiple 301 Connections; and 303 * Explicit support for multistreaming and multipath transport 304 protocols, and the grouping of related Connections into Connection 305 Groups through cloning of Connections, to allow applications to 306 take full advantage of new transport protocols supporting these 307 features. 309 4. API Summary 311 The Transport Services API is the basic common abstract application 312 programming interface to the Transport Services Architecture defined 313 in the TAPS Architecture [I-D.ietf-taps-arch]. 315 An application primarily interacts with this API through two Objects: 316 Preconnections and Connections. A Preconnection represents a set of 317 properties and constraints on the selection and configuration of 318 paths and protocols to establish a Connection with a remote Endpoint. 319 A Connection represents a transport Protocol Stack on which data can 320 be sent to and/or received from a remote Endpoint (i.e., depending on 321 the kind of transport, connections can be bi-directional or 322 unidirectional). Connections can be created from Preconnections in 323 three ways: by initiating the Preconnection (i.e., actively opening, 324 as in a client), through listening on the Preconnection (i.e., 325 passively opening, as in a server), or rendezvousing on the 326 Preconnection (i.e. peer to peer establishment). 328 Once a Connection is established, data can be sent and received on it 329 in the form of Messages. The interface supports the preservation of 330 message boundaries both via explicit Protocol Stack support, and via 331 application support through a Message Framer which finds message 332 boundaries in a stream. Messages are received asynchronously through 333 event handlers registered by the application. Errors and other 334 notifications also happen asynchronously on the Connection. It is 335 not necessary for an application to handle all events; some events 336 may have implementation-specific default handlers. The application 337 should not assume that ignoring events (e.g. errors) is always safe. 339 Section 5, Section 6, Section 7, Section 8, and Section 11 describe 340 the details of application interaction with Objects through Actions 341 and Events in each phase of a Connection, following the phases (Pre- 342 Establishment, Establishment, Data Transfer, and Termination) 343 described in Section 4.1 of [I-D.ietf-taps-arch]. 345 4.1. Usage Examples 347 The following usage examples illustrate how an application might use 348 a Transport Services Interface to: 350 * Act as a server, by listening for incoming connections, receiving 351 requests, and sending responses, see Section 4.1.1. 353 * Act as a client, by connecting to a remote endpoint using 354 Initiate, sending requests, and receiving responses, see 355 Section 4.1.2. 357 * Act as a peer, by connecting to a remote endpoint using Rendezvous 358 while simultaneously waiting for incoming Connections, sending 359 Messages, and receiving Messages, see Section 4.1.3. 361 The examples in this section presume that a transport protocol is 362 available between the endpoints that provides Reliable Data Transfer, 363 Preservation of data ordering, and Preservation of Message 364 Boundaries. In this case, the application can choose to receive only 365 complete messages. 367 If none of the available transport protocols provides Preservation of 368 Message Boundaries, but there is a transport protocol that provides a 369 reliable ordered byte stream, an application may receive this byte 370 stream as partial Messages and transform it into application-layer 371 Messages. Alternatively, an application may provide a Message 372 Framer, which can transform a byte stream into a sequence of Messages 373 (Section 9). 375 4.1.1. Server Example 377 This is an example of how an application might listen for incoming 378 Connections using the Transport Services Interface, receive a 379 request, and send a response. 381 LocalSpecifier := NewLocalEndpoint() 382 LocalSpecifier.WithInterface("any") 383 LocalSpecifier.WithService("https") 385 TransportProperties := NewTransportProperties() 386 TransportProperties.Require(preserve-msg-boundaries) 387 // Reliable Data Transfer and Preserve Order are Required by default 389 SecurityParameters := NewSecurityParameters() 390 SecurityParameters.AddIdentity(identity) 391 SecurityParameters.AddPrivateKey(privateKey, publicKey) 393 // Specifying a remote endpoint is optional when using Listen() 394 Preconnection := NewPreconnection(LocalSpecifier, 395 TransportProperties, 396 SecurityParameters) 398 Listener := Preconnection.Listen() 400 Listener -> ConnectionReceived 402 // Only receive complete messages in a Conn.Received handler 403 Connection.Receive() 405 Connection -> Received 407 //---- Receive event handler begin ---- 408 Connection.Send(messageDataResponse) 409 Connection.Close() 411 // Stop listening for incoming Connections 412 // (this example supports only one Connection) 413 Listener.Stop() 414 //---- Receive event handler end ---- 416 4.1.2. Client Example 418 This is an example of how an application might connect to a remote 419 application using the Transport Services Interface, send a request, 420 and receive a response. 422 RemoteSpecifier := NewRemoteEndpoint() 423 RemoteSpecifier.WithHostname("example.com") 424 RemoteSpecifier.WithService("https") 426 TransportProperties := NewTransportProperties() 427 TransportProperties.Require(preserve-msg-boundaries) 428 // Reliable Data Transfer and Preserve Order are Required by default 430 SecurityParameters := NewSecurityParameters() 431 TrustCallback := NewCallback({ 432 // Verify identity of the remote endpoint, return the result 433 }) 434 SecurityParameters.SetTrustVerificationCallback(TrustCallback) 436 // Specifying a local endpoint is optional when using Initiate() 437 Preconnection := NewPreconnection(RemoteSpecifier, 438 TransportProperties, 439 SecurityParameters) 441 Connection := Preconnection.Initiate() 443 Connection -> Ready<> 445 //---- Ready event handler begin ---- 446 Connection.Send(messageDataRequest) 448 // Only receive complete messages 449 Connection.Receive() 450 //---- Ready event handler end ---- 452 Connection -> Received 454 // Close the Connection in a Receive event handler 455 Connection.Close() 457 4.1.3. Peer Example 459 This is an example of how an application might establish a connection 460 with a peer using Rendezvous(), send a Message, and receive a 461 Message. 463 LocalSpecifier := NewLocalEndpoint() 464 LocalSpecifier.WithPort(9876) 466 RemoteSpecifier := NewRemoteEndpoint() 467 RemoteSpecifier.WithHostname("example.com") 468 RemoteSpecifier.WithPort(9877) 470 TransportProperties := NewTransportProperties() 471 TransportProperties.Require(preserve-msg-boundaries) 472 // Reliable Data Transfer and Preserve Order are Required by default 474 SecurityParameters := NewSecurityParameters() 475 SecurityParameters.AddIdentity(identity) 476 SecurityParameters.AddPrivateKey(privateKey, publicKey) 478 TrustCallback := New Callback({ 479 // Verify identity of the remote endpoint, return the result 480 }) 481 SecurityParameters.SetTrustVerificationCallback(trustCallback) 483 // Both local and remote endpoint must be specified 484 Preconnection := NewPreconnection(LocalSpecifier, 485 RemoteSpecifier, 486 TransportProperties, 487 SecurityParameters) 489 Preconnection.Rendezvous() 491 Preconnection -> RendezvousDone 493 //---- Ready event handler begin ---- 494 Connection.Send(messageDataRequest) 496 // Only receive complete messages 497 Connection.Receive() 498 //---- Ready event handler end ---- 500 Connection -> Received 502 // Close the Connection in a Receive event handler 503 Connection.Close() 505 4.2. Transport Properties 507 Each application using the Transport Services Interface declares its 508 preferences for how the transport service should operate using 509 properties at each stage of the lifetime of a connection using 510 Transport Properties, as defined in [I-D.ietf-taps-arch]. 512 Transport Properties are divided into Selection, Connection, and 513 Message Properties. During pre-establishment, Selection Properties 514 (see Section 5.2) are used to specify which paths and protocol stacks 515 can be used and are preferred by the application, and Connection 516 Properties (see Section 10.1) can be used to influence decisions made 517 during establishment and to fine-tune the eventually established 518 connection. These Connection Properties can also be used later, to 519 monitor and fine-tune established connections. The behavior of the 520 selected protocol stack(s) when sending Messages is controlled by 521 Message Properties (see Section 7.5). 523 All Transport Properties, regardless of the phase in which they are 524 used, are organized within a single namespace. This enables setting 525 them as defaults in earlier stages and querying them in later stages: 527 * Connection Properties can be set on Preconnections 529 * Message Properties can be set on Preconnections and Connections 531 * The effect of Selection Properties can be queried on Connections 532 and Messages 534 Note that configuring Connection Properties and Message Properties on 535 Preconnections is preferred over setting them later. Early 536 specification of Connection Properties allows their use as additional 537 input to the selection process. Protocol Specific Properties, which 538 enable configuration of specialized features of a specific protocol, 539 see Section 3.2 of [I-D.ietf-taps-arch], are not used as an input to 540 the selection process but only support configuration if the 541 respective prototocol has been selected. 543 4.2.1. Transport Property Names 545 Transport Properties are referred to by property names. These names 546 are lower-case strings whereby words are separated by hyphens. These 547 names serve two purposes: 549 * Allow different components of a TAPS implementation to pass 550 Transport Properties, e.g., between a language frontend and a 551 policy manager, or as a representation of properties retrieved 552 from a file or other storage. 554 * Make code of different TAPS implementations look similar. 556 Transport Property Names are hierarchically organized in the form 557 [.]. 559 * The Namespace part MUST be empty for well-known, generic 560 properties, i.e., for properties that are not specific to a 561 protocol and are defined in an RFC. 563 * Protocol Specific Properties MUST use the protocol acronym as 564 Namespace, e.g., "tcp" for TCP specific Transport Properties. For 565 IETF protocols, property names under these namespaces SHOULD be 566 defined in an RFC. 568 * Vendor or implementation specific properties MUST use a string 569 identifying the vendor or implementation as Namespace. 571 Namespaces for the keywords provided in the IANA protocol numbers 572 registry (see https://www.iana.org/assignments/protocol-numbers/ 573 protocol-numbers.xhtml) are reserved for Protocol Specific Properties 574 and MUST not be used for vendor or implementation specific 575 properties. 577 4.2.2. Transport Property Types 579 Transport Properties can have one of a set of data types: 581 * Boolean: can take the values "true" and "false"; representation is 582 implementation-dependent. 584 * Integer: can take positive or negative numeric integer values; 585 range and representation is implementation-dependent. 587 * Numeric: can take positive or negative numeric values; range and 588 representation is implementation-dependent. 590 * Enumeration: can take one value of a finite set of values, 591 dependent on the property itself. The representation is 592 implementation dependent; however, implementations MUST provide a 593 method for the application to determine the entire set of possible 594 values for each property. 596 * Preference: can take one of five values (Prohibit, Avoid, Ignore, 597 Prefer, Require) for the level of preference of a given property 598 during protocol selection; see Section 5.2. 600 4.3. Scope of the Interface Definition 602 This document defines a language- and platform-independent interface 603 to a Transport Services system. Given the wide variety of languages 604 and language conventions used to write applications that use the 605 transport layer to connect to other applications over the Internet, 606 this independence makes this interface necessarily abstract. 608 There is no interoperability benefit in tightly defining how the 609 interface is presented to application programmers across diverse 610 platforms. However, maintaining the "shape" of the abstract 611 interface across these platforms reduces the effort for programmers 612 who learn the transport services interface to then apply their 613 knowledge across multiple platforms. 615 We therefore make the following recommendations: 617 * Actions, Events, and Errors in implementations of this interface 618 SHOULD use the names given for them in the document, subject to 619 capitalization, punctuation, and other typographic conventions in 620 the language of the implementation, unless the implementation 621 itself uses different names for substantially equivalent objects 622 for networking by convention. 624 * Implementations of this interface SHOULD implement each Selection 625 Property, Connection Property, and Message Context Property 626 specified in this document. Each interface SHOULD be implemented 627 even when this will always result in no operation, e.g. there is 628 no action when the API specifies a Property that is not available 629 in a transport protocol implemented on a specific platform. For 630 example, if TCP is the only underlying transport protocol, the 631 Message Property "msg-ordered" can be implemented even if 632 disabling ordering will not have any effect TCP because the API 633 does not guarantee out-of-order delivery. Similarly, the msg- 634 lifetime" Message Property can be implemented but ignored, as the 635 description of this Property states that "it is not guaranteed 636 that a Message will not be sent when its Lifetime has expired". 638 * Implementations may use other representations for Transport 639 Property Names, e.g., by providing constants, but should provide a 640 straight-forward mapping between their representation and the 641 property names specified here. 643 5. Pre-Establishment Phase 645 The Pre-Establishment phase allows applications to specify properties 646 for the Connections they are about to make, or to query the API about 647 potential Connections they could make. 649 A Preconnection Object represents a potential Connection. It has 650 state that describes properties of a Connection that might exist in 651 the future. This state comprises Local Endpoint and Remote Endpoint 652 Objects that denote the endpoints of the potential Connection (see 653 Section 5.1), the Selection Properties (see Section 5.2), any 654 preconfigured Connection Properties (Section 10.1), and the security 655 parameters (see Section 5.3): 657 Preconnection := NewPreconnection(LocalEndpoint?, 658 RemoteEndpoint?, 659 TransportProperties, 660 SecurityParams) 662 The Local Endpoint MUST be specified if the Preconnection is used to 663 Listen() for incoming Connections, but is OPTIONAL if it is used to 664 Initiate() connections. The Remote Endpoint MUST be specified if the 665 Preconnection is used to Initiate() Connections, but is OPTIONAL if 666 it is used to Listen() for incoming Connections. The Local Endpoint 667 and the Remote Endpoint MUST both be specified if a peer-to-peer 668 Rendezvous is to occur based on the Preconnection. 670 Message Framers (see Section 9), if required, should be added to the 671 Preconnection during pre-establishment. 673 5.1. Specifying Endpoints 675 The transport services API uses the Local Endpoint and Remote 676 Endpoint Objects to refer to the endpoints of a transport connection. 677 Actions on these Objects can be used to represent various different 678 types of endpoint identifiers, such as IP addresses, DNS names, and 679 interface names, as well as port numbers and service names. 681 Specify a Remote Endpoint using a hostname and service name: 683 RemoteSpecifier := NewRemoteEndpoint() 684 RemoteSpecifier.WithHostname("example.com") 685 RemoteSpecifier.WithService("https") 687 Specify a Remote Endpoint using an IPv6 address and remote port: 689 RemoteSpecifier := NewRemoteEndpoint() 690 RemoteSpecifier.WithIPv6Address(2001:db8:4920:e29d:a420:7461:7073:0a) 691 RemoteSpecifier.WithPort(443) 693 Specify a Remote Endpoint using an IPv4 address and remote port: 695 RemoteSpecifier := NewRemoteEndpoint() 696 RemoteSpecifier.WithIPv4Address(192.0.2.21) 697 RemoteSpecifier.WithPort(443) 699 Specify a Local Endpoint using a local interface name and local port: 701 LocalSpecifier := NewLocalEndpoint() 702 LocalSpecifier.WithInterface("en0") 703 LocalSpecifier.WithPort(443) 704 As an alternative to specifying an interface name for the Local 705 Endpoint, an application can express more fine-grained preferences 706 using the "Interface Instance or Type" Selection Property, see 707 Section 5.2.10. However, if the application specifies Selection 708 Properties which are inconsistent with the Local Endpoint, this will 709 result in an error once the application attempts to open a 710 Connection. 712 Specify a Local Endpoint using a STUN server: 714 LocalSpecifier := NewLocalEndpoint() 715 LocalSpecifier.WithStunServer(address, port, credentials) 717 Specify a Local Endpoint using a Any-Source Multicast group to join 718 on a named local interface: 720 LocalSpecifier := NewLocalEndpoint() 721 LocalSpecifier.WithIPv4Address(233.252.0.0) 722 LocalSpecifier.WithInterface("en0") 724 Source-Specific Multicast requires setting both a Local and Remote 725 Endpoint: 727 LocalSpecifier := NewLocalEndpoint() 728 LocalSpecifier.WithIPv4Address(232.1.1.1) 729 LocalSpecifier.WithInterface("en0") 731 RemoteSpecifier := NewRemoteEndpoint() 732 RemoteSpecifier.WithIPv4Address(192.0.2.22) 734 Implementations may also support additional endpoint representations 735 and provide a single NewEndpoint() call that takes different endpoint 736 representations. 738 Multiple endpoint identifiers can be specified for each Local 739 Endpoint and Remote Endpoint. For example, a Local Endpoint could be 740 configured with two interface names, or a Remote Endpoint could be 741 specified via both IPv4 and IPv6 addresses. These multiple 742 identifiers refer to the same transport endpoint. 744 The transport services API resolves names internally, when the 745 Initiate(), Listen(), or Rendezvous() method is called to establish a 746 Connection. The API explicitly does not require the application to 747 resolve names, though there is a tradeoff between early and late 748 binding of addresses to names. Early binding allows the API 749 implementation to reduce connection setup latency, at the cost of 750 potentially limited scope for alternate path discovery during 751 Connection establishment, as well as potential additional information 752 leakage about application interest when used with a resolution method 753 (such as DNS without TLS) which does not protect query 754 confidentiality. 756 The Resolve() action on Preconnection can be used by the application 757 to force early binding when required, for example with some Network 758 Address Translator (NAT) traversal protocols (see Section 6.3). 760 Specifying a multicast group address on the Local Endpoint will 761 indicate to the transport system that the resulting connection will 762 be used to receive multicast messages. The Remote Endpoint can be 763 used to filter by specific senders. This will restrict the 764 application to establishing the Preconnection by calling Listen(). 765 The accepted Connections are receive-only. 767 Similarly, specifying a multicast group address on the Remote 768 Endpoint will indicate that the resulting connection will be used to 769 send multicast messages. 771 5.2. Specifying Transport Properties 773 A Preconnection Object holds properties reflecting the application's 774 requirements and preferences for the transport. These include 775 Selection Properties for selecting protocol stacks and paths, as well 776 as Connection Properties for configuration of the detailed operation 777 of the selected Protocol Stacks. 779 The protocol(s) and path(s) selected as candidates during 780 establishment are determined and configured using these properties. 781 Since there could be paths over which some transport protocols are 782 unable to operate, or remote endpoints that support only specific 783 network addresses or transports, transport protocol selection is 784 necessarily tied to path selection. This may involve choosing 785 between multiple local interfaces that are connected to different 786 access networks. 788 Most Selection Properties are represented as preferences, which can 789 have one of five preference levels: 791 +------------+----------------------------------------+ 792 | Preference | Effect | 793 +============+========================================+ 794 | Require | Select only protocols/paths providing | 795 | | the property, fail otherwise | 796 +------------+----------------------------------------+ 797 | Prefer | Prefer protocols/paths providing the | 798 | | property, proceed otherwise | 799 +------------+----------------------------------------+ 800 | Ignore | No preference | 801 +------------+----------------------------------------+ 802 | Avoid | Prefer protocols/paths not providing | 803 | | the property, proceed otherwise | 804 +------------+----------------------------------------+ 805 | Prohibit | Select only protocols/paths not | 806 | | providing the property, fail otherwise | 807 +------------+----------------------------------------+ 809 Table 1 811 In addition, the pseudo-level "Default" can be used to reset the 812 property to the default level used by the implementation. This level 813 will never show up when queuing the value of a preference - the 814 effective preference must be returned instead. 816 The implementation MUST ensure an outcome that is consistent with 817 application requirements as expressed using Require and Prohibit. 818 While preferences expressed using Prefer and Avoid influence protocol 819 and path selection as well, outcomes may vary given the same 820 Selection Properties, as the available protocols and paths may vary 821 across systems and contexts. However, implementations are 822 RECOMMENDED to aim to provide a consistent outcome to an application, 823 given the same Selection Properties. 825 Note that application preferences may conflict with each other. For 826 example, if an application indicates a preference for a specific path 827 by specifying an interface, but also a preference for a protocol, a 828 situation might occur in which the preferred protocol is not 829 available on the preferred path. In such cases, implementations 830 SHOULD prioritize Selection Properties that select paths over those 831 that select protocols. Therefore, the transport system SHOULD race 832 the path first, ignoring the protocol preference if the protocol does 833 not work on the path. 835 Selection and Connection Properties, as well as defaults for Message 836 Properties, can be added to a Preconnection to configure the 837 selection process and to further configure the eventually selected 838 protocol stack(s). They are collected into a TransportProperties 839 object to be passed into a Preconnection object: 841 TransportProperties := NewTransportProperties() 843 Individual properties are then added to the TransportProperties 844 Object: 846 TransportProperties.Add(property, value) 848 Selection Properties of type "Preference" can be frequently used. 849 Implementations MAY therefore provide additional convenience 850 functions, see Appendix A.1 for examples. In addition, 851 implementations MAY provide a mechanism to create TransportProperties 852 objects that are preconfigured for common use cases as outlined in 853 Appendix A.2. 855 For an existing Connection, the Transport Properties can be queried 856 any time by using the following call on the Connection Object: 858 TransportProperties := Connection.GetTransportProperties() 860 A Connection gets its Transport Properties either by being explicitly 861 configured via a Preconnection, by configuration after establishment, 862 or by inheriting them from an antecedent via cloning; see Section 6.4 863 for more. 865 Section 10.1 provides a list of Connection Properties, while 866 Selection Properties are listed in the subsections below. Note that 867 many properties are only considered during establishment, and can not 868 be changed after a Connection is established; however, they can be 869 queried. Querying a Selection Property after establishment yields 870 the value "Require" for properties of the selected protocol and path, 871 Avoid for properties avoided during selection, and Ignore for all 872 other properties. 874 An implementation of this interface must provide sensible defaults 875 for Selection Properties. The defaults given for each property below 876 represent a configuration that can be implemented over TCP. An 877 alternate set of default Protocol Selection Properties would 878 represent a configuration that can be implemented over UDP. 880 5.2.1. Reliable Data Transfer (Connection) 882 Name: reliability 884 Type: Preference 885 Default: Require 887 This property specifies whether the application needs to use a 888 transport protocol that ensures that all data is received on the 889 other side without corruption. This also entails being notified when 890 a Connection is closed or aborted. 892 5.2.2. Preservation of Message Boundaries 894 Name: preserve-msg-boundaries 896 Type: Preference 898 Default: Prefer 900 This property specifies whether the application needs or prefers to 901 use a transport protocol that preserves message boundaries. 903 5.2.3. Configure Per-Message Reliability 905 Name: per-msg-reliability 907 Type: Preference 909 Default: Ignore 911 This property specifies whether an application considers it useful to 912 indicate its reliability requirements on a per-Message basis. This 913 property applies to Connections and Connection Groups. 915 5.2.4. Preservation of Data Ordering 917 Name: preserve-order 919 Type: Preference 921 Default: Require 923 This property specifies whether the application wishes to use a 924 transport protocol that can ensure that data is received by the 925 application on the other end in the same order as it was sent. 927 5.2.5. Use 0-RTT Session Establishment with an Idempotent Message 929 Name: zero-rtt-msg 931 Type: Preference 932 Default: Ignore 934 This property specifies whether an application would like to supply a 935 Message to the transport protocol before Connection establishment, 936 which will then be reliably transferred to the other side before or 937 during Connection establishment, potentially multiple times (i.e., 938 multiple copies of the message data may be passed to the Remote 939 Endpoint). See also Section 7.5.4. Note that disabling this 940 property has no effect for protocols that are not connection-oriented 941 and do not protect against duplicated messages, e.g., UDP. 943 5.2.6. Multistream Connections in Group 945 Name: multistreaming 947 Type: Preference 949 Default: Prefer 951 This property specifies that the application would prefer multiple 952 Connections within a Connection Group to be provided by streams of a 953 single underlying transport connection where possible. 955 5.2.7. Full Checksum Coverage on Sending 957 Name: per-msg-checksum-len-send 959 Type: Preference 961 Default: Require 963 This property specifies whether the application desires protection 964 against corruption for all data transmitted on this Connection. 965 Disabling this property may enable to control checksum coverage later 966 (see Section 7.5.6). 968 5.2.8. Full Checksum Coverage on Receiving 970 Name: per-msg-checksum-len-recv 972 Type: Preference 974 Default: Require 976 This property specifies whether the application desires protection 977 against corruption for all data received on this Connection. 979 5.2.9. Congestion control 981 Name: congestion-control 983 Type: Preference 985 Default: Require 987 This property specifies whether the application would like the 988 Connection to be congestion controlled or not. Note that if a 989 Connection is not congestion controlled, an application using such a 990 Connection should itself perform congestion control in accordance 991 with [RFC2914]. Also note that reliability is usually combined with 992 congestion control in protocol implementations, rendering "reliable 993 but not congestion controlled" a request that is unlikely to succeed. 995 5.2.10. Interface Instance or Type 997 Name: interface 999 Type: Set (Preference, Enumeration) 1001 Default: Empty set (not setting a preference for any interface) 1003 This property allows the application to select which specific network 1004 interfaces or categories of interfaces it wants to "Require", 1005 "Prohibit", "Prefer", or "Avoid". Note that marking a specific 1006 interface as "Require" strictly limits path selection to a single 1007 interface, and may often lead to less flexible and resilient 1008 connection establishment. 1010 In contrast to other Selection Properties, this property is a tuple 1011 of an (Enumerated) interface identifier and a preference, and can 1012 either be implemented directly as such, or for making one preference 1013 available for each interface and interface type available on the 1014 system. 1016 The set of valid interface types is implementation- and system- 1017 specific. For example, on a mobile device, there may be "Wi-Fi" and 1018 "Cellular" interface types available; whereas on a desktop computer, 1019 there may be "Wi-Fi" and "Wired Ethernet" interface types available. 1020 An implementation should provide all types that are supported on the 1021 local system to all remote systems, to allow applications to be 1022 written generically. For example, if a single implementation is used 1023 on both mobile devices and desktop devices, it should define the 1024 "Cellular" interface type for both systems, since an application may 1025 want to always "Prohibit Cellular". Note that marking a specific 1026 interface type as "Require" limits path selection to a small set of 1027 interfaces, and leads to less flexible and resilient connection 1028 establishment. 1030 The set of interface types is expected to change over time as new 1031 access technologies become available. 1033 Interface types should not be treated as a proxy for properties of 1034 interfaces such as metered or unmetered network access. If an 1035 application needs to prohibit metered interfaces, this should be 1036 specified via Provisioning Domain attributes (see Section 5.2.11) or 1037 another specific property. 1039 5.2.11. Provisioning Domain Instance or Type 1041 Name: pvd 1043 Type: Set (Preference, Enumeration) 1045 Default: Empty set (not setting a preference for any PvD) 1047 Similar to interface instances and types (see Section 5.2.10), this 1048 property allows the application to control path selection by 1049 selecting which specific Provisioning Domains or categories of 1050 Provisioning Domains it wants to "Require", "Prohibit", "Prefer", or 1051 "Avoid". Provisioning Domains define consistent sets of network 1052 properties that may be more specific than network interfaces 1053 [RFC7556]. 1055 As with interface instances and types, this property is a tuple of an 1056 (Enumerated) PvD identifier and a preference, and can either be 1057 implemented directly as such, or for making one preference available 1058 for each interface and interface type available on the system. 1060 The identification of a specific Provisioning Domain (PvD) is defined 1061 to be implementation- and system-specific, since there is not a 1062 portable standard format for a PvD identitfier. For example, this 1063 identifier may be a string name or an integer. As with requiring 1064 specific interfaces, requiring a specific PvD strictly limits path 1065 selection. 1067 Categories or types of PvDs are also defined to be implementation- 1068 and system-specific. These may be useful to identify a service that 1069 is provided by a PvD. For example, if an application wants to use a 1070 PvD that provides a Voice-Over-IP service on a Cellular network, it 1071 can use the relevant PvD type to require some PvD that provides this 1072 service, without needing to look up a particular instance. While 1073 this does restrict path selection, it is broader than requiring 1074 specific PvD instances or interface instances, and should be 1075 preferred over these options. 1077 5.2.12. Use Temporary Local Address 1079 Name: use-temporary-local-address 1081 Type: Preference 1083 Default: Avoid for Listeners and Rendezvous Connections. Prefer for 1084 other Connections. 1086 This property allows the application to express a preference for the 1087 use of temporary local addresses, sometimes called "privacy" 1088 addresses [RFC4941]. Temporary addresses are generally used to 1089 prevent linking connections over time when a stable address, 1090 sometimes called "permanent" address, is not needed. Note that if an 1091 application Requires the use of temporary addresses, the resulting 1092 Connection cannot use IPv4, as temporary addresses do not exist in 1093 IPv4. 1095 5.2.13. Parallel Use of Multiple Paths 1097 Name: multipath 1099 Type: Enumeration 1101 Default: Disabled 1103 This property specifies whether an application wants to take 1104 advantage of transferring data across multiple paths between the same 1105 end hosts. Using multiple paths allows connections to migrate 1106 between interfaces as availability and performance properties change. 1107 Possible values are: 1109 Disabled: The connection will not attempt using multiple paths once 1110 established 1112 Handover: The connection should attempt to migrate between different 1113 paths upon interface availability changes 1115 Interactive: The connection should attempt to use multiple paths in 1116 response to loss or delay upon individual paths 1118 Aggregate: The connection should attempt to use multiple paths in 1119 parallel in order to maximize bandwidth 1121 Enumeration values other than "Disabled" are interpreted as 1122 preferences. 1124 5.2.14. Direction of communication 1126 Name: direction 1128 Type: Enumeration 1130 Default: Bidirectional 1132 This property specifies whether an application wants to use the 1133 connection for sending and/or receiving data. Possible values are: 1135 Bidirectional: The connection must support sending and receiving 1136 data 1138 Unidirectional send: The connection must support sending data, and 1139 the application cannot use the connection to receive any data 1141 Unidirectional receive: The connection must support receiving data, 1142 and the application cannot use the connection to send any data 1144 Since unidirectional communication can be supported by transports 1145 offering bidirectional communication, specifying unidirectional 1146 communication may cause a transport stack that supports bidirectional 1147 communication to be selected. 1149 5.2.15. Notification of excessive retransmissions 1151 Name: retransmit-notify 1153 Type: Preference 1155 Default: Ignore 1157 This property specifies whether an application considers it useful to 1158 be informed in case sent data was retransmitted more often than a 1159 certain threshold (see Section 10.1.1 for configuration of this 1160 threshold). 1162 5.2.16. Notification of ICMP soft error message arrival 1164 Name: soft-error-notify 1166 Type: Preference 1168 Default: Ignore 1169 This property specifies whether an application considers it useful to 1170 be informed when an ICMP error message arrives that does not force 1171 termination of a connection. When set to true, received ICMP errors 1172 will be available as SoftErrors, see Section 10.3.1. Note that even 1173 if a protocol supporting this property is selected, not all ICMP 1174 errors will necessarily be delivered, so applications cannot rely on 1175 receiving them. 1177 5.3. Specifying Security Parameters and Callbacks 1179 Most security parameters, e.g., TLS ciphersuites, local identity and 1180 private key, etc., may be configured statically. Others are 1181 dynamically configured during connection establishment. Thus, we 1182 partition security parameters and callbacks based on their place in 1183 the lifetime of connection establishment. Similar to Transport 1184 Properties, both parameters and callbacks are inherited during 1185 cloning (see Section 6.4). 1187 5.3.1. Pre-Connection Parameters 1189 Common parameters such as TLS ciphersuites are known to 1190 implementations. Clients should use common safe defaults for these 1191 values whenever possible. However, as discussed in 1192 [I-D.ietf-taps-transport-security], many transport security protocols 1193 require specific security parameters and constraints from the client 1194 at the time of configuration and actively during a handshake. These 1195 configuration parameters are created as follows: 1197 SecurityParameters := NewSecurityParameters() 1199 Security configuration parameters and sample usage follow: 1201 * Local identity and private keys: Used to perform private key 1202 operations and prove one's identity to the Remote Endpoint. 1203 (Note, if private keys are not available, e.g., since they are 1204 stored in hardware security modules (HSMs), handshake callbacks 1205 must be used. See below for details.) 1207 SecurityParameters.AddIdentity(identity) 1208 SecurityParameters.AddPrivateKey(privateKey, publicKey) 1210 * Supported algorithms: Used to restrict what parameters are used by 1211 underlying transport security protocols. When not specified, 1212 these algorithms should use known and safe defaults for the 1213 system. Parameters include: ciphersuites, supported groups, and 1214 signature algorithms. 1216 SecurityParameters.AddSupportedGroup(secp256k1) 1217 SecurityParameters.AddCiphersuite(TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256) 1218 SecurityParameters.AddSignatureAlgorithm(ed25519) 1220 * Session cache management: Used to tune cache capacity, lifetime, 1221 re-use, and eviction policies, e.g., LRU or FIFO. Constants and 1222 policies for these interfaces are implementation-specific. 1224 SecurityParameters.SetSessionCacheCapacity(MAX_CACHE_ELEMENTS) 1225 SecurityParameters.SetSessionCacheLifetime(SECONDS_PER_DAY) 1226 SecurityParameters.SetSessionCachePolicy(CachePolicyOneTimeUse) 1228 * Pre-Shared Key import: Used to install pre-shared keying material 1229 established out-of-band. Each pre-shared keying material is 1230 associated with some identity that typically identifies its use or 1231 has some protocol-specific meaning to the Remote Endpoint. 1233 SecurityParameters.AddPreSharedKey(key, identity) 1235 5.3.2. Connection Establishment Callbacks 1237 Security decisions, especially pertaining to trust, are not static. 1238 Once configured, parameters may also be supplied during connection 1239 establishment. These are best handled as client-provided callbacks. 1240 Security handshake callbacks that may be invoked during connection 1241 establishment include: 1243 * Trust verification callback: Invoked when a Remote Endpoint's 1244 trust must be validated before the handshake protocol can proceed. 1246 TrustCallback := NewCallback({ 1247 // Handle trust, return the result 1248 }) 1249 SecurityParameters.SetTrustVerificationCallback(trustCallback) 1251 * Identity challenge callback: Invoked when a private key operation 1252 is required, e.g., when local authentication is requested by a 1253 remote. 1255 ChallengeCallback := NewCallback({ 1256 // Handle challenge 1257 }) 1258 SecurityParameters.SetIdentityChallengeCallback(challengeCallback) 1260 6. Establishing Connections 1262 Before a Connection can be used for data transfer, it must be 1263 established. Establishment ends the pre-establishment phase; all 1264 transport properties and cryptographic parameter specification must 1265 be complete before establishment, as these will be used to select 1266 candidate Paths and Protocol Stacks for the Connection. 1267 Establishment may be active, using the Initiate() Action; passive, 1268 using the Listen() Action; or simultaneous for peer-to-peer, using 1269 the Rendezvous() Action. These Actions are described in the 1270 subsections below. 1272 6.1. Active Open: Initiate 1274 Active open is the Action of establishing a Connection to a Remote 1275 Endpoint presumed to be listening for incoming Connection requests. 1276 Active open is used by clients in client-server interactions. Active 1277 open is supported by this interface through the Initiate Action: 1279 Connection := Preconnection.Initiate(timeout?) 1281 The timeout parameter specifies how long to wait before aborting 1282 Active open. Before calling Initiate, the caller must have populated 1283 a Preconnection Object with a Remote Endpoint specifier, optionally a 1284 Local Endpoint specifier (if not specified, the system will attempt 1285 to determine a suitable Local Endpoint), as well as all properties 1286 necessary for candidate selection. 1288 The Initiate() Action returns a Connection object. Once Initiate() 1289 has been called, any changes to the Preconnection MUST NOT have any 1290 effect on the Connection. However, the Preconnection can be reused, 1291 e.g., to Initiate another Connection. 1293 Once Initiate is called, the candidate Protocol Stack(s) may cause 1294 one or more candidate transport-layer connections to be created to 1295 the specified remote endpoint. The caller may immediately begin 1296 sending Messages on the Connection (see Section 7) after calling 1297 Initate(); note that any idempotent data sent while the Connection is 1298 being established may be sent multiple times or on multiple 1299 candidates. 1301 The following Events may be sent by the Connection after Initiate() 1302 is called: 1304 Connection -> Ready<> 1306 The Ready Event occurs after Initiate has established a transport- 1307 layer connection on at least one usable candidate Protocol Stack over 1308 at least one candidate Path. No Receive Events (see Section 8) will 1309 occur before the Ready Event for Connections established using 1310 Initiate. 1312 Connection -> InitiateError 1314 An InitiateError occurs either when the set of transport properties 1315 and security parameters cannot be fulfilled on a Connection for 1316 initiation (e.g. the set of available Paths and/or Protocol Stacks 1317 meeting the constraints is empty) or reconciled with the local and/or 1318 remote Endpoints; when the remote specifier cannot be resolved; or 1319 when no transport-layer connection can be established to the remote 1320 Endpoint (e.g. because the remote Endpoint is not accepting 1321 connections, the application is prohibited from opening a Connection 1322 by the operating system, or the establishment attempt has timed out 1323 for any other reason). 1325 See also Section 7.8 to combine Connection establishment and 1326 transmission of the first message in a single action. 1328 6.2. Passive Open: Listen 1330 Passive open is the Action of waiting for Connections from remote 1331 Endpoints, commonly used by servers in client-server interactions. 1332 Passive open is supported by this interface through the Listen Action 1333 and returns a Listener object: 1335 Listener := Preconnection.Listen() 1337 Before calling Listen, the caller must have initialized the 1338 Preconnection during the pre-establishment phase with a Local 1339 Endpoint specifier, as well as all properties necessary for Protocol 1340 Stack selection. A Remote Endpoint may optionally be specified, to 1341 constrain what Connections are accepted. 1343 The Listen() Action returns a Listener object. Once Listen() has 1344 been called, any changes to the Preconnection MUST NOT have any 1345 effect on the Listener. The Preconnection can be disposed of or 1346 reused, e.g., to create another Listener. 1348 Listening continues until the global context shuts down, or until the 1349 Stop action is performed on the Listener object: 1351 Listener.Stop() 1353 After Stop() is called, the Listener can be disposed of. 1355 Listener -> ConnectionReceived 1356 The ConnectionReceived Event occurs when a Remote Endpoint has 1357 established a transport-layer connection to this Listener (for 1358 Connection-oriented transport protocols), or when the first Message 1359 has been received from the Remote Endpoint (for Connectionless 1360 protocols), causing a new Connection to be created. The resulting 1361 Connection is contained within the ConnectionReceived Event, and is 1362 ready to use as soon as it is passed to the application via the 1363 event. 1365 Listener.SetNewConnectionLimit(value) 1367 If the caller wants to rate-limit the number of inbound Connections 1368 that will be delivered, it can set a cap using 1369 SetNewConnectionLimit(). This mechanism allows a server to protect 1370 itself from being drained of resources. Each time a new Connection 1371 is delivered by the ConnectionReceived Event, the value is 1372 automatically decremented. Once the value reaches zero, no further 1373 Connections will be delivered until the caller sets the limit to a 1374 higher value. By default, this value is Infinite. The caller is 1375 also able to reset the value to Infinite at any point. 1377 Listener -> ListenError 1379 A ListenError occurs either when the Properties and Security 1380 Parameters of the Preconnection cannot be fulfilled for listening or 1381 cannot be reconciled with the Local Endpoint (and/or Remote Endpoint, 1382 if specified), when the Local Endpoint (or Remote Endpoint, if 1383 specified) cannot be resolved, or when the application is prohibited 1384 from listening by policy. 1386 Listener -> Stopped<> 1388 A Stopped Event occurs after the Listener has stopped listening. 1390 6.3. Peer-to-Peer Establishment: Rendezvous 1392 Simultaneous peer-to-peer Connection establishment is supported by 1393 the Rendezvous() Action: 1395 Preconnection.Rendezvous() 1397 The Preconnection Object must be specified with both a Local Endpoint 1398 and a Remote Endpoint, and also the transport properties and security 1399 parameters needed for Protocol Stack selection. 1401 The Rendezvous() Action causes the Preconnection to listen on the 1402 Local Endpoint for an incoming Connection from the Remote Endpoint, 1403 while simultaneously trying to establish a Connection from the Local 1404 Endpoint to the Remote Endpoint. This corresponds to a TCP 1405 simultaneous open, for example. 1407 The Rendezvous() Action returns a Connection object. Once 1408 Rendezvous() has been called, any changes to the Preconnection MUST 1409 NOT have any effect on the Connection. However, the Preconnection 1410 can be reused, e.g., for Rendezvous of another Connection. 1412 Preconnection -> RendezvousDone 1414 The RendezvousDone<> Event occurs when a Connection is established 1415 with the Remote Endpoint. For Connection-oriented transports, this 1416 occurs when the transport-layer connection is established; for 1417 Connectionless transports, it occurs when the first Message is 1418 received from the Remote Endpoint. The resulting Connection is 1419 contained within the RendezvousDone<> Event, and is ready to use as 1420 soon as it is passed to the application via the Event. 1422 Preconnection -> RendezvousError 1424 An RendezvousError occurs either when the Properties and Security 1425 Parameters of the Preconnection cannot be fulfilled for rendezvous or 1426 cannot be reconciled with the Local and/or Remote Endpoints, when the 1427 Local Endpoint or Remote Endpoint cannot be resolved, when no 1428 transport-layer connection can be established to the Remote Endpoint, 1429 or when the application is prohibited from rendezvous by policy. 1431 When using some NAT traversal protocols, e.g., Interactive 1432 Connectivity Establishment (ICE) [RFC5245], it is expected that the 1433 Local Endpoint will be configured with some method of discovering NAT 1434 bindings, e.g., a Session Traversal Utilities for NAT (STUN) server. 1435 In this case, the Local Endpoint may resolve to a mixture of local 1436 and server reflexive addresses. The Resolve() action on the 1437 Preconnection can be used to discover these bindings: 1439 []Preconnection := Preconnection.Resolve() 1441 The Resolve() call returns a list of Preconnection Objects, that 1442 represent the concrete addresses, local and server reflexive, on 1443 which a Rendezvous() for the Preconnection will listen for incoming 1444 Connections. These resolved Preconnections will share all other 1445 Properties with the Preconnection from which they are derived, though 1446 some Properties may be made more-specific by the resolution process. 1447 This list can be passed to a peer via a signalling protocol, such as 1448 SIP [RFC3261] or WebRTC [RFC7478], to configure the remote. 1450 6.4. Connection Groups 1452 Entangled Connections can be created using the Clone Action: 1454 Connection := Connection.Clone() 1456 Calling Clone on a Connection yields a group of two Connections: the 1457 parent Connection on which Clone was called, and the resulting cloned 1458 Connection. These connections are "entangled" with each other, and 1459 become part of a Connection Group. Calling Clone on any of these two 1460 Connections adds a third Connection to the Connection Group, and so 1461 on. Connections in a Connection Group generally share Connection 1462 Properties. However, there may be exceptions, such as "Priority 1463 (Connection)", see Section 10.1.3. Like all other Properties, 1464 Priority is copied to the new Connection when calling Clone(), but it 1465 is not entangled: Changing Priority on one Connection does not change 1466 it on the other Connections in the same Connection Group. 1468 In addition, incoming entangled Connections can be received by 1469 creating a Listener on an existing connection: 1471 Listener := Connection.ListenClone() 1473 ListenClone() creates a Listener that listens on the same 1474 LocalEndpoint as the one the cloned Connection is using. Any new 1475 Connection received by this Listener will be entangled with the 1476 cloned Connection. Changing one of the Connection Properties on one 1477 Connection in the group changes it for all others. Message 1478 Properties, however, are not entangled. For example, changing 1479 "Timeout for aborting Connection" (see Section 10.1.4) on one 1480 Connection in a group will automatically change this Connection 1481 Property for all Connections in the group in the same way. However, 1482 changing "Lifetime" (see Section 7.5.1) of a Message will only affect 1483 a single Message on a single Connection, entangled or not. 1485 If the underlying protocol supports multi-streaming, it is natural to 1486 use this functionality to implement Clone. In that case, entangled 1487 Connections are multiplexed together, giving them similar treatment 1488 not only inside endpoints but also across the end-to-end Internet 1489 path. 1491 Note that calling Clone() may result in on-the-wire signaling, e.g., 1492 to open a new connection, depending on the underlying Protocol Stack. 1493 When Clone() leads to multiple connections being opened instead of 1494 multi-streaming, the transport system will ensure consistency of 1495 Connection Properties by uniformly applying them to all underlying 1496 connections in a group. Even in such a case, there are possibilities 1497 for a transport system to implement prioritization within a 1498 Connection Group [TCP-COUPLING] [RFC8699]. 1500 Attempts to clone a Connection can result in a CloneError: 1502 Connection -> CloneError 1504 The Connection Property "Priority" operates on entangled Connections 1505 as in Section 7.5.2: when allocating available network capacity among 1506 Connections in a Connection Group, sends on Connections with higher 1507 Priority values will be prioritized over sends on Connections with 1508 lower Priority values. A transport system implementation should, if 1509 possible, assign each Connection the capacity share (M-N) x C / M, 1510 where N is the Connection's Priority value, M is the maximum Priority 1511 value used by all Connections in the group and C is the total 1512 available capacity. However, the Priority setting is purely 1513 advisory, and no guarantees are given about the way capacity is 1514 shared. Each implementation is free to implement a way to share 1515 capacity that it sees fit. 1517 7. Sending Data 1519 Once a Connection has been established, it can be used for sending 1520 data. Data is sent as Messages, which allow the application to 1521 communicate the boundaries of the data being transferred. By 1522 default, Send enqueues a complete Message, and takes optional per- 1523 Message properties (see Section 7.1). All Send actions are 1524 asynchronous, and deliver events (see Section 7.3). Sending partial 1525 Messages for streaming large data is also supported (see 1526 Section 7.6). 1528 Messages are sent on a Connection using the Send action: 1530 Connection.Send(messageData, messageContext?, endOfMessage?) 1532 where messageData is the data object to send. 1534 The optional messageContext parameter allows adding Message 1535 Properties as described in Section 7.5. Moreover, the messageContext 1536 can be used to identify Send Events related to a specific Message 1537 (see Section 7.3) or to inspect meta-data related to the Message sent 1538 (see Section 7.4). 1540 The optional endOfMessage parameter supports partial sending and is 1541 described in Section 7.6. 1543 Framers can be used to extend or modify the message data with 1544 additional information that can be processed at the receiver to 1545 detect message boundaries. This is further decribed in Section 9. 1547 7.1. Basic Sending 1549 The most basic form of sending on a connection involves enqueuing a 1550 single Data block as a complete Message, with default Message 1551 Properties. Message data is transferred as an array of bytes, and 1552 the resulting object contains both the byte array and the length of 1553 the array. 1555 messageData := "hello".bytes() 1556 Connection.Send(messageData) 1558 The interpretation of a Message to be sent is dependent on the 1559 implementation, and on the constraints on the Protocol Stacks implied 1560 by the Connection's transport properties. For example, a Message may 1561 be a single datagram for UDP Connections; or an HTTP Request for HTTP 1562 Connections. 1564 Some transport protocols can deliver arbitrarily sized Messages, but 1565 other protocols constrain the maximum Message size. Applications can 1566 query the Connection Property "Maximum Message size on send" 1567 (Section 10.1.8.3) to determine the maximum size allowed for a single 1568 Message. If a Message is too large to fit in the Maximum Message 1569 Size for the Connection, the Send will fail with a SendError event 1570 (Section 7.3.3). For example, it is invalid to send a Message over a 1571 UDP connection that is larger than the available datagram sending 1572 size. 1574 7.2. Sending Replies 1576 When a message is sent in response to a message received, the 1577 application may use the Message Context of the received Message to 1578 construct a Message Context for the reply. 1580 replyMessageContext := requestMessageContext.reply() 1582 By using the "replyMessageContext", the transport system is informed 1583 that the message to be sent is a response and can map the response to 1584 the same underlying transport connection or stream the request was 1585 received from. The concept of Message Contexts is described in 1586 Section 7.4. 1588 7.3. Send Events 1590 Like all Actions in this interface, the Send Action is asynchronous. 1591 There are several Events that can be delivered in response to Sending 1592 a Message. Exactly one Event (Sent, Expired, or SendError) will be 1593 delivered in reponse to each call to Send. 1595 Note that if partial Sends are used (Section 7.6), there will still 1596 be exactly one Send Event delivered for each call to Send. For 1597 example, if a Message expired while two requests to Send data for 1598 that Message are outstanding, there will be two Expired events 1599 delivered. 1601 7.3.1. Sent 1603 Connection -> Sent 1605 The Sent Event occurs when a previous Send Action has completed, 1606 i.e., when the data derived from the Message has been passed down or 1607 through the underlying Protocol Stack and is no longer the 1608 responsibility of this interface. The exact disposition of the 1609 Message (i.e., whether it has actually been transmitted, moved into a 1610 buffer on the network interface, moved into a kernel buffer, and so 1611 on) when the Sent Event occurs is implementation-specific. The Sent 1612 Event contains a reference to the Message to which it applies. 1614 Sent Events allow an application to obtain an understanding of the 1615 amount of buffering it creates. That is, if an application calls the 1616 Send Action multiple times without waiting for a Sent Event, it has 1617 created more buffer inside the transport system than an application 1618 that always waits for the Sent Event before calling the next Send 1619 Action. 1621 7.3.2. Expired 1623 Connection -> Expired 1625 The Expired Event occurs when a previous Send Action expired before 1626 completion; i.e. when the Message was not sent before its Lifetime 1627 (see Section 7.5.1) expired. This is separate from SendError, as it 1628 is an expected behavior for partially reliable transports. The 1629 Expired Event contains a reference to the Message to which it 1630 applies. 1632 7.3.3. SendError 1634 Connection -> SendError 1635 A SendError occurs when a Message could not be sent due to an error 1636 condition: an attempt to send a Message which is too large for the 1637 system and Protocol Stack to handle, some failure of the underlying 1638 Protocol Stack, or a set of Message Properties not consistent with 1639 the Connection's transport properties. The SendError contains a 1640 reference to the Message to which it applies. 1642 7.4. Message Contexts 1644 Using the MessageContext object, the application can set and retrieve 1645 meta-data of the message, including Message Properties (see 1646 Section 7.5) and framing meta-data (see Section 9.2). Therefore, a 1647 MessageContext object can be passed to the Send action and is 1648 returned by each Send and Receive related event. 1650 Message Properties can be set and queried using the Message Context: 1652 MessageContext.add(scope?, parameter, value) 1653 PropertyValue := MessageContext.get(scope?, property) 1655 To get or set Message Properties, the optional scope parameter is 1656 left empty. To get or set meta-data for a Framer, the application 1657 has to pass a reference to this Framer as the scope parameter. 1659 For MessageContexts returned by send events (see Section 7.3) and 1660 receive events (see Section 8.2), the application can query 1661 information about the local and remote endpoint: 1663 RemoteEndpoint := MessageContext.GetRemoteEndpoint() 1664 LocalEndpoint := MessageContext.GetLocalEndpoint() 1666 Message Contexts can also be used to send messages that are flagged 1667 as a reply to other messages, see Section 7.2 for details. If the 1668 message received was sent by the remote endpoint as a reply to an 1669 earlier message and the Protocol Stack provides this information, the 1670 MessageContext of the original request can be accessed using the 1671 Message Context of the reply: 1673 RequestMessageContext := MessageContext.GetOriginalRequest() 1675 7.5. Message Properties 1677 Applications may need to annotate the Messages they send with extra 1678 information to control how data is scheduled and processed by the 1679 transport protocols in the Connection. Therefore a message context 1680 containing these properties can be passed to the Send Action. For 1681 other uses of the message context, see Section 7.4. 1683 Note that Message Properties are per-Message, not per-Send if partial 1684 Messages are sent (Section 7.6). All data blocks associated with a 1685 single Message share properties specified in the Message Contexts. 1686 For example, it would not make sense to have the beginning of a 1687 Message expire, but allow the end of a Message to still be sent. 1689 A MessageContext object contains metadata for Messages to be sent or 1690 received. 1692 messageData := "hello".bytes() 1693 messageContext := NewMessageContext() 1694 messageContext.add(parameter, value) 1695 Connection.Send(messageData, messageContext) 1697 The simpler form of Send, which does not take any messageContext, is 1698 equivalent to passing a default MessageContext without adding any 1699 Message Properties to it. 1701 If an application wants to override Message Properties for a specific 1702 message, it can acquire an empty MessageContext Object and add all 1703 desired Message Properties to that Object. It can then reuse the 1704 same messageContext Object for sending multiple Messages with the 1705 same properties. 1707 Properties may be added to a MessageContext object only before the 1708 context is used for sending. Once a messageContext has been used 1709 with a Send call, modifying any of its properties is invalid. 1711 Message Properties may be inconsistent with the properties of the 1712 Protocol Stacks underlying the Connection on which a given Message is 1713 sent. For example, a Connection must provide reliability to allow 1714 setting an infinite value for the lifetime property of a Message. 1715 Sending a Message with Message Properties inconsistent with the 1716 Selection Properties of the Connection yields an error. 1718 The following Message Properties are supported: 1720 7.5.1. Lifetime 1722 Name: msg-lifetime 1724 Type: Numeric 1726 Default: infinite 1728 Lifetime specifies how long a particular Message can wait to be sent 1729 to the remote endpoint before it is irrelevant and no longer needs to 1730 be (re-)transmitted. This is a hint to the transport system - it is 1731 not guaranteed that a Message will not be sent when its Lifetime has 1732 expired. 1734 Setting a Message's Lifetime to infinite indicates that the 1735 application does not wish to apply a time constraint on the 1736 transmission of the Message, but it does not express a need for 1737 reliable delivery; reliability is adjustable per Message via the 1738 "Reliable Data Transfer (Message)" property (see Section 7.5.7). The 1739 type and units of Lifetime are implementation-specific. 1741 7.5.2. Priority 1743 Name: msg-prio 1745 Type: Integer (non-negative) 1747 Default: 100 1749 This property represents a hierarchy of priorities. It can specify 1750 the priority of a Message, relative to other Messages sent over the 1751 same Connection. 1753 A Message with Priority 0 will yield to a Message with Priority 1, 1754 which will yield to a Message with Priority 2, and so on. Priorities 1755 may be used as a sender-side scheduling construct only, or be used to 1756 specify priorities on the wire for Protocol Stacks supporting 1757 prioritization. 1759 Note that this property is not a per-message override of the 1760 connection Priority - see Section 10.1.3. Both Priority properties 1761 may interact, but can be used independently and be realized by 1762 different mechanisms. 1764 7.5.3. Ordered 1766 Name: msg-ordered 1768 Type: Boolean 1770 Default: true 1772 If true, it specifies that the receiver-side transport protocol stack 1773 may only deliver the Message to the receiving application after the 1774 previous ordered Message which was passed to the same Connection via 1775 the Send Action, when such a Message exists. If false, the Message 1776 may be delivered to the receiving application out of order. This 1777 property is used for protocols that support preservation of data 1778 ordering, see Section 5.2.4, but allow out-of-order delivery for 1779 certain messages, e.g., by multiplexing independent messages onto 1780 different streams. 1782 7.5.4. Idempotent 1784 Name: idempotent 1786 Type: Boolean 1788 Default: false 1790 If true, it specifies that a Message is safe to send to the remote 1791 endpoint more than once for a single Send Action. It is used to mark 1792 data safe for certain 0-RTT establishment techniques, where 1793 retransmission of the 0-RTT data may cause the remote application to 1794 receive the Message multiple times. 1796 Note that for protocols that do not protect against duplicated 1797 messages, e.g., UDP, all messages MUST be marked as Idempotent. In 1798 order to enable protocol selection to choose such a protocol, 1799 Idempotent MUST be added to the TransportProperties passed to the 1800 Preconnection. If such a protocol was chosen, disabling Idempotent 1801 on individual messages MUST result in a SendError. 1803 7.5.5. Final 1805 Type: Boolean 1807 Name: final 1809 Default: false 1811 If true, this Message is the last one that the application will send 1812 on a Connection. This allows underlying protocols to indicate to the 1813 Remote Endpoint that the Connection has been effectively closed in 1814 the sending direction. For example, TCP-based Connections can send a 1815 FIN once a Message marked as Final has been completely sent, 1816 indicated by marking endOfMessage. Protocols that do not support 1817 signalling the end of a Connection in a given direction will ignore 1818 this property. 1820 Note that a Final Message must always be sorted to the end of a list 1821 of Messages. The Final property overrides Priority and any other 1822 property that would re-order Messages. If another Message is sent 1823 after a Message marked as Final has already been sent on a 1824 Connection, the Send Action for the new Message will cause a 1825 SendError Event. 1827 7.5.6. Corruption Protection Length 1829 Name: msg-checksum-len 1831 Type: Integer (non-negative with -1 as special value) 1833 Default: -1 (full coverage) 1835 This property specifies the minimum length of the section of the 1836 Message, starting from byte 0, that the application requires to be 1837 delivered without corruption due to lower layer errors. It is used 1838 to specify options for simple integrity protection via checksums. A 1839 value of 0 means that no checksum is required, and -1 means that the 1840 entire Message is protected by a checksum. Only full coverage is 1841 guaranteed, any other requests are advisory, meaning that full 1842 coverage is applied anyway. 1844 7.5.7. Reliable Data Transfer (Message) 1846 Name: msg-reliable 1848 Type: Boolean 1850 Default: true 1852 When true, this property specifies that a message should be sent in 1853 such a way that the transport protocol ensures all data is received 1854 on the other side without corruption. Changing the 'Reliable Data 1855 Transfer' property on Messages is only possible for Connections that 1856 were established with the Selection Property 'Configure Per-Message 1857 Reliability' enabled. When this is not the case, changing it will 1858 generate an error. Disabling this property indicates that the 1859 transport system may disable retransmissions or other reliability 1860 mechanisms for this particular Message, but such disabling is not 1861 guaranteed. 1863 7.5.8. Message Capacity Profile Override 1865 Name: msg-capacity-profile 1867 Type: Enumeration 1869 This enumerated property specifies the application's preferred 1870 tradeoffs for sending this Message; it is a per-Message override of 1871 the Capacity Profile connection property (see Section 10.1.6). 1873 7.5.9. Singular Transmission 1874 Name: singular-transmission 1876 Type: Boolean 1878 Default: false 1880 This property specifies that a message should be sent and received as 1881 a single packet without transport-layer segmentation or network-layer 1882 fragmentation, if possible. Attempts to send a message with this 1883 property set with a size greater to the transport's current estimate 1884 of its maximum transmission segment size will result in a 1885 "SendError". When used with transports supporting this functionality 1886 and running over IP version 4, the Don't Fragment bit will be set. 1888 7.6. Partial Sends 1890 It is not always possible for an application to send all data 1891 associated with a Message in a single Send Action. The Message data 1892 may be too large for the application to hold in memory at one time, 1893 or the length of the Message may be unknown or unbounded. 1895 Partial Message sending is supported by passing an endOfMessage 1896 boolean parameter to the Send Action. This value is always true by 1897 default, and the simpler forms of Send are equivalent to passing true 1898 for endOfMessage. 1900 The following example sends a Message in two separate calls to Send. 1902 messageContext := NewMessageContext() 1903 messageContext.add(parameter, value) 1905 messageData := "hel".bytes() 1906 endOfMessage := false 1907 Connection.Send(messageData, messageContext, endOfMessage) 1909 messageData := "lo".bytes() 1910 endOfMessage := true 1911 Connection.Send(messageData, messageContext, endOfMessage) 1913 All data sent with the same MessageContext object will be treated as 1914 belonging to the same Message, and will constitute an in-order series 1915 until the endOfMessage is marked. Once the end of the Message is 1916 marked, the MessageContext object may be re-used as a new Message 1917 with identical parameters. 1919 7.7. Batching Sends 1921 To reduce the overhead of sending multiple small Messages on a 1922 Connection, the application may want to batch several Send actions 1923 together. This provides a hint to the system that the sending of 1924 these Messages should be coalesced when possible, and that sending 1925 any of the batched Messages may be delayed until the last Message in 1926 the batch is enqueued. 1928 Connection.Batch( 1929 Connection.Send(messageData) 1930 Connection.Send(messageData) 1931 ) 1933 7.8. Send on Active Open: InitiateWithSend 1935 For application-layer protocols where the Connection initiator also 1936 sends the first message, the InitiateWithSend() action combines 1937 Connection initiation with a first Message sent: 1939 Connection := Preconnection.InitiateWithSend(messageData, messageContext?, timeout?) 1941 Whenever possible, a messageContext should be provided to declare the 1942 message passed to InitiateWithSend as idempotent. This allows the 1943 transport system to make use of 0-RTT establishment in case this is 1944 supported by the available protocol stacks. When the selected 1945 stack(s) do not support transmitting data upon connection 1946 establishment, InitiateWithSend is identical to Initiate() followed 1947 by Send(). 1949 Neither partial sends nor send batching are supported by 1950 InitiateWithSend(). 1952 The Events that may be sent after InitiateWithSend() are equivalent 1953 to those that would be sent by an invocation of Initate() followed 1954 immediately by an invocation of Send(), with the caveat that a send 1955 failure that occurs because the Connection could not be established 1956 will not result in a SendError separate from the InitiateError 1957 signaling the failure of Connection establishment. 1959 8. Receiving Data 1961 Once a Connection is established, it can be used for receiving data. 1962 As with sending, data is received in terms of Messages. Receiving is 1963 an asynchronous operation, in which each call to Receive enqueues a 1964 request to receive new data from the connection. Once data has been 1965 received, or an error is encountered, an event will be delivered to 1966 complete any pending Receive requests (see Section 8.2). If Messages 1967 arrive at the transport system before Receive requests are issued, 1968 ensuing Receive requests will first operate on these Messages before 1969 awaiting any further Messages. 1971 8.1. Enqueuing Receives 1973 Receive takes two parameters to specify the length of data that an 1974 application is willing to receive, both of which are optional and 1975 have default values if not specified. 1977 Connection.Receive(minIncompleteLength?, maxLength?) 1979 By default, Receive will try to deliver complete Messages in a single 1980 event (Section 8.2.1). 1982 The application can set a minIncompleteLength value to indicate the 1983 smallest partial Message data size in bytes that should be delivered 1984 in response to this Receive. By default, this value is infinite, 1985 which means that only complete Messages should be delivered (see 1986 Section 8.2.2 and Section 9 for more information on how this is 1987 accomplished). If this value is set to some smaller value, the 1988 associated receive event will be triggered only when at least that 1989 many bytes are available, or the Message is complete with fewer 1990 bytes, or the system needs to free up memory. Applications should 1991 always check the length of the data delivered to the receive event 1992 and not assume it will be as long as minIncompleteLength in the case 1993 of shorter complete Messages or memory issues. 1995 The maxLength argument indicates the maximum size of a Message in 1996 bytes the application is currently prepared to receive. The default 1997 value for maxLength is infinite. If an incoming Message is larger 1998 than the minimum of this size and the maximum Message size on receive 1999 for the Connection's Protocol Stack, it will be delivered via 2000 ReceivedPartial events (Section 8.2.2). 2002 Note that maxLength does not guarantee that the application will 2003 receive that many bytes if they are available; the interface may 2004 return ReceivedPartial events with less data than maxLength according 2005 to implementation constraints. Note also that maxLength and 2006 minIncompleteLength are intended only to manage buffering, and are 2007 not interpreted as a receiver preference for message reordering. 2009 8.2. Receive Events 2011 Each call to Receive will be paired with a single Receive Event, 2012 which can be a success or an error. This allows an application to 2013 provide backpressure to the transport stack when it is temporarily 2014 not ready to receive messages. 2016 8.2.1. Received 2018 Connection -> Received 2020 A Received event indicates the delivery of a complete Message. It 2021 contains two objects, the received bytes as messageData, and the 2022 metadata and properties of the received Message as messageContext. 2024 The messageData object provides access to the bytes that were 2025 received for this Message, along with the length of the byte array. 2026 The messageContext is provided to enable retrieving metadata about 2027 the message and referring to the message, e.g., to send replies and 2028 map responses to their requests. See Section 7.4 for details. 2030 See Section 9 for handling Message framing in situations where the 2031 Protocol Stack only provides a byte-stream transport. 2033 8.2.2. ReceivedPartial 2035 Connection -> ReceivedPartial 2037 If a complete Message cannot be delivered in one event, one part of 2038 the Message may be delivered with a ReceivedPartial event. In order 2039 to continue to receive more of the same Message, the application must 2040 invoke Receive again. 2042 Multiple invocations of ReceivedPartial deliver data for the same 2043 Message by passing the same MessageContext, until the endOfMessage 2044 flag is delivered or a ReceiveError occurs. All partial blocks of a 2045 single Message are delivered in order without gaps. This event does 2046 not support delivering discontiguous partial Messages. 2048 If the minIncompleteLength in the Receive request was set to be 2049 infinite (indicating a request to receive only complete Messages), 2050 the ReceivedPartial event may still be delivered if one of the 2051 following conditions is true: 2053 * the underlying Protocol Stack supports message boundary 2054 preservation, and the size of the Message is larger than the 2055 buffers available for a single message; 2057 * the underlying Protocol Stack does not support message boundary 2058 preservation, and the Message Framer (see Section 9) cannot 2059 determine the end of the message using the buffer space it has 2060 available; or 2062 * the underlying Protocol Stack does not support message boundary 2063 preservation, and no Message Framer was supplied by the 2064 application 2066 Note that in the absence of message boundary preservation or a 2067 Message Framer, all bytes received on the Connection will be 2068 represented as one large Message of indeterminate length. 2070 8.2.3. ReceiveError 2072 Connection -> ReceiveError 2074 A ReceiveError occurs when data is received by the underlying 2075 Protocol Stack that cannot be fully retrieved or parsed, or when some 2076 other indication is received that reception has failed. In contrast, 2077 conditions that irrevocably lead to the termination of the Connection 2078 are signaled using ConnectionError instead (see Section 11). 2080 The ReceiveError event passes an optional associated MessageContext. 2081 This may indicate that a Message that was being partially received 2082 previously, but had not completed, encountered an error and will not 2083 be completed. 2085 8.3. Receive Message Properties 2087 Each Message Context may contain metadata from protocols in the 2088 Protocol Stack; which metadata is available is Protocol Stack 2089 dependent. These are exposed though additional read-only Message 2090 Properties that can be queried from the MessageContext object (see 2091 Section 7.4) passed by the receive event. The following metadata 2092 values are supported: 2094 8.3.1. UDP(-Lite)-specific Property: ECN 2096 When available, Message metadata carries the value of the Explicit 2097 Congestion Notification (ECN) field. This information can be used 2098 for logging and debugging purposes, and for building applications 2099 which need access to information about the transport internals for 2100 their own operation. This property is specific to UDP and UDP-Lite 2101 because these protocols do not implement congestion control, and 2102 hence expose this functionality to the application. 2104 8.3.2. Early Data 2106 In some cases it may be valuable to know whether data was read as 2107 part of early data transfer (before connection establishment has 2108 finished). This is useful if applications need to treat early data 2109 separately, e.g., if early data has different security properties 2110 than data sent after connection establishment. In the case of TLS 2111 1.3, client early data can be replayed maliciously (see [RFC8446]). 2112 Thus, receivers may wish to perform additional checks for early data 2113 to ensure it is idempotent or not replayed. If TLS 1.3 is available 2114 and the recipient Message was sent as part of early data, the 2115 corresponding metadata carries a flag indicating as such. If early 2116 data is enabled, applications should check this metadata field for 2117 Messages received during connection establishment and respond 2118 accordingly. 2120 8.3.3. Receiving Final Messages 2122 The Message Context can indicate whether or not this Message is the 2123 Final Message on a Connection. For any Message that is marked as 2124 Final, the application can assume that there will be no more Messages 2125 received on the Connection once the Message has been completely 2126 delivered. This corresponds to the Final property that may be marked 2127 on a sent Message, see Section 7.5.5. 2129 Some transport protocols and peers may not support signaling of the 2130 Final property. Applications therefore should not rely on receiving 2131 a Message marked Final to know that the other endpoint is done 2132 sending on a connection. 2134 Any calls to Receive once the Final Message has been delivered will 2135 result in errors. 2137 9. Message Framers 2139 Although most applications communicate over a network using well- 2140 formed Messages, the boundaries and metadata of the Messages are 2141 often not directly communicated by the transport protocol itself. 2142 For example, HTTP applications send and receive HTTP messages over a 2143 byte-stream transport, requiring that the boundaries of HTTP messages 2144 be parsed out from the stream of bytes. 2146 Message Framers allow extending a Connection's Protocol Stack to 2147 define how to encapsulate or encode outbound Messages, and how to 2148 decapsulate or decode inbound data into Messages. Message Framers 2149 allow message boundaries to be preserved when using a Connection 2150 object, even when using byte-stream transports. This facility is 2151 designed based on the fact that many of the current application 2152 protocols evolved over TCP, which does not provide message boundary 2153 preservation, and since many of these protocols require message 2154 boundaries to function, each application layer protocol has defined 2155 its own framing. 2157 Note that while Message Framers add the most value when placed above 2158 a protocol that otherwise does not preserve message boundaries, they 2159 can also be used with datagram- or message-based protocols. In these 2160 cases, they add an additional transformation to further encode or 2161 encapsulate, and can potentially support packing multiple 2162 application-layer Messages into individual transport datagrams. 2164 The API to implement a Message Framer can vary depending on the 2165 implementation; guidance on implementing Message Framers can be found 2166 in [I-D.ietf-taps-impl]. 2168 9.1. Adding Message Framers to Connections 2170 The Message Framer object can be added to one or more Preconnections 2171 to run on top of transport protocols. Multiple Framers may be added. 2172 If multiple Framers are added, the last one added runs first when 2173 framing outbound messages, and last when parsing inbound data. 2175 The following example adds a basic HTTP Message Framer to a 2176 Preconnection: 2178 framer := NewHTTPMessageFramer() 2179 Preconnection.AddFramer(framer) 2181 9.2. Framing Meta-Data 2183 When sending Messages, applications can add specific Message values 2184 to a MessageContext (Section 7.4) that is intended for a Framer. 2185 This can be used, for example, to set the type of a Message for a TLV 2186 format. The namespace of values is custom for each unique Message 2187 Framer. 2189 messageContext := NewMessageContext() 2190 messageContext.add(framer, key, value) 2191 Connection.Send(messageData, messageContext) 2193 When an application receives a MessageContext in a Receive event, it 2194 can also look to see if a value was set by a specific Message Framer. 2196 messageContext.get(framer, key) -> value 2198 For example, if an HTTP Message Framer is used, the values could 2199 correspond to HTTP headers: 2201 httpFramer := NewHTTPMessageFramer() 2202 ... 2203 messageContext := NewMessageContext() 2204 messageContext.add(httpFramer, "accept", "text/html") 2206 10. Managing Connections 2208 During pre-establishment and after establishment, connections can be 2209 configured and queried using Connection Properties, and asynchronous 2210 information may be available about the state of the connection via 2211 Soft Errors. 2213 Connection Properties represent the configuration and state of the 2214 selected Protocol Stack(s) backing a Connection. These Connection 2215 Properties may be Generic, applying regardless of transport protocol, 2216 or Specific, applicable to a single implementation of a single 2217 transport protocol stack. Generic Connection Properties are defined 2218 in Section 10.1 below. Specific Protocol Properties are defined in a 2219 transport- and implementation-specific way, and must not be assumed 2220 to apply across different protocols. Attempts to set Specific 2221 Protocol Properties on a protocol stack not containing that specific 2222 protocol are simply ignored, and do not raise an error; however, too 2223 much reliance by an application on Specific Protocol Properties may 2224 significantly reduce the flexibility of a transport services 2225 implementation. 2227 The application can set and query Connection Properties on a per- 2228 Connection basis. Connection Properties that are not read-only can 2229 be set during pre-establishment (see Section 5.2), as well as on 2230 connections directly using the SetProperty action: 2232 Connection.SetProperty(property, value) 2234 Note that changing one of the Connection Properties on one Connection 2235 in a Connection Group will also change it for all other Connections 2236 of that group; see further Section 6.4. 2238 At any point, the application can query Connection Properties. 2240 ConnectionProperties := Connection.GetProperties() 2242 Depending on the status of the connection, the queried Connection 2243 Properties will include different information: 2245 * The connection state, which can be one of the following: 2246 Establishing, Established, Closing, or Closed. 2248 * Whether the connection can be used to send data. A connection can 2249 not be used for sending if the connection was created with the 2250 Selection Property "Direction of Communication" set to 2251 "unidirectional receive" or if a Message marked as "Final" was 2252 sent over this connection, see Section 7.5.5. 2254 * Whether the connection can be used to receive data. A connection 2255 can not be used for reading if the connection was created with the 2256 Selection Property "Direction of Communication" set to 2257 "unidirectional send" or if a Message marked as "Final" was 2258 received, see Section 8.3.3. The latter is only supported by 2259 certain transport protocols, e.g., by TCP as half-closed 2260 connection. 2262 * For Connections that are Establishing: Transport Properties that 2263 the application specified on the Preconnection, see Section 5.2. 2265 * For Connections that are Established, Closing, or Closed: 2266 Selection (Section 5.2) and Connection Properties (Section 10.1) 2267 of the actual protocols that were selected and instantiated. 2268 Selection Properties indicate whether or not the Connection has or 2269 offers a certain Selection Property. Note that the actually 2270 instantiated protocol stack may not match all Protocol Selection 2271 Properties that the application specified on the Preconnection. 2272 For example, a certain Protocol Selection Property that an 2273 application specified as Preferred may not actually be present in 2274 the chosen protocol stack because none of the currently available 2275 transport protocols had this feature. 2277 * For Connections that are Established, additional properties of the 2278 path(s) in use. These properties can be derived from the local 2279 provisioning domain [RFC7556], measurements by the Protocol Stack, 2280 or other sources. 2282 10.1. Generic Connection Properties 2284 Generic Connection Properties are defined independent of the chosen 2285 protocol stack and therefore available on all Connections. 2287 Note that many Connection Properties have a corresponding Selection 2288 Property which enables applications to express their preference for 2289 protocols providing a supporting transport feature. 2291 10.1.1. Retransmission Threshold Before Excessive Retransmission 2292 Notification 2294 Name: retransmit-notify-threshold 2296 Type: Integer 2298 Default: -1 2300 This property specifies after how many retransmissions to inform the 2301 application about "Excessive Retransmissions". The special value -1 2302 means that this notification is disabled. 2304 10.1.2. Required Minimum Corruption Protection Coverage for Receiving 2306 Name: recv-checksum-len 2308 Type: Integer 2310 Default: -1 2312 This property specifies the part of the received data that needs to 2313 be covered by a checksum. It is given in Bytes. A value of 0 means 2314 that no checksum is required, and the special value -1 indicates full 2315 checksum coverage. 2317 10.1.3. Priority (Connection) 2319 Name: conn-prio 2321 Type: Integer 2323 Default: 100 2325 This Property is a non-negative integer representing the relative 2326 inverse priority (i.e., a lower value reflects a higher priority) of 2327 this Connection relative to other Connections in the same Connection 2328 Group. It has no effect on Connections not part of a Connection 2329 Group. As noted in Section 6.4, this property is not entangled when 2330 Connections are cloned, i.e., changing the Priority on one Connection 2331 in a Connection Group does not change it on the other Connections in 2332 the same Connection Group. 2334 10.1.4. Timeout for Aborting Connection 2336 Name: conn-timeout 2338 Type: Numeric 2340 Default: -1 2342 This property specifies how long to wait before deciding that a 2343 Connection has failed when trying to reliably deliver data to the 2344 destination. Adjusting this Property will only take effect when the 2345 underlying stack supports reliability. The special value -1 means 2346 that this timeout is not scheduled to happen. This can be a valid 2347 choice with unreliable data transfer (e.g., when UDP is the 2348 underlying transport protocol). 2350 10.1.5. Connection Group Transmission Scheduler 2352 Name: conn-scheduler 2354 Type: Enumeration 2356 Default: Weighted Fair Queueing (see Section 3.6 in [RFC8260]) 2358 This property specifies which scheduler should be used among 2359 Connections within a Connection Group, see Section 6.4. The set of 2360 schedulers can be taken from [RFC8260]. 2362 10.1.6. Capacity Profile 2364 Name: conn-capacity-profile 2366 This property specifies the desired network treatment for traffic 2367 sent by the application and the tradeoffs the application is prepared 2368 to make in path and protocol selection to receive that desired 2369 treatment. When the capacity profile is set to a value other than 2370 Default, the transport system SHOULD select paths and configure 2371 protocols to optimize the tradeoff between delay, delay variation, 2372 and bandwidth efficiency based on the capacity profile specified. 2373 How this is realized is implementation-specific. The Capacity 2374 Profile MAY also be used to set priorities on the wire for Protocol 2375 Stacks supporting prioritization. Recommendations for use with DSCP 2376 are provided below for each profile; note that when a Connection is 2377 multiplexed, the guidelines in Section 6 of [RFC7657] apply. 2379 The following values are valid for the Capacity Profile: 2381 Default: The application provides no information about its expected 2382 capacity profile. Transport system implementations that map the 2383 requested capacity profile onto per-connection DSCP signaling 2384 SHOULD assign the DSCP Default Forwarding [RFC2474] PHB. 2386 Scavenger: The application is not interactive. It expects to send 2387 and/or receive data without any urgency. This can, for example, 2388 be used to select protocol stacks with scavenger transmission 2389 control and/or to assign the traffic to a lower-effort service. 2390 Transport system implementations that map the requested capacity 2391 profile onto per-connection DSCP signaling SHOULD assign the DSCP 2392 Less than Best Effort [RFC8622] PHB. 2394 Low Latency/Interactive: The application is interactive, and prefers 2395 loss to latency. Response time should be optimized at the expense 2396 of bandwidth efficiency and delay variation when sending on this 2397 connection. This can be used by the system to disable the 2398 coalescing of multiple small Messages into larger packets (Nagle's 2399 algorithm); to prefer immediate acknowledgment from the peer 2400 endpoint when supported by the underlying transport; and so on. 2401 Transport system implementations that map the requested capacity 2402 profile onto per-connection DSCP signaling without multiplexing 2403 SHOULD assign a DSCP Assured Forwarding (AF41,AF42,AF43,AF44) 2404 [RFC2597] PHB. Inelastic traffic that is expected to conform to 2405 the configured network service rate could be mapped to the DSCP 2406 Expedited Forwarding [RFC3246] or [RFC5865] PHBs. 2408 Low Latency/Non-Interactive: The application prefers loss to latency 2409 but is not interactive. Response time should be optimized at the 2410 expense of bandwidth efficiency and delay variation when sending 2411 on this connection. Transport system implementations that map the 2412 requested capacity profile onto per-connection DSCP signaling 2413 without multiplexing SHOULD assign a DSCP Assured Forwarding 2414 (AF21,AF22,AF23,AF24) [RFC2597] PHB. 2416 Constant-Rate Streaming: The application expects to send/receive 2417 data at a constant rate after Connection establishment. Delay and 2418 delay variation should be minimized at the expense of bandwidth 2419 efficiency. This implies that the Connection may fail if the 2420 desired rate cannot be maintained across the Path. A transport 2421 may interpret this capacity profile as preferring a circuit 2422 breaker [RFC8084] to a rate-adaptive congestion controller. 2423 Transport system implementations that map the requested capacity 2424 profile onto per-connection DSCP signaling without multiplexing 2425 SHOULD assign a DSCP Assured Forwarding (AF31,AF32,AF33,AF34) 2426 [RFC2597] PHB. 2428 High Throughput Data: The application expects to send/receive data 2429 at the maximum rate allowed by its congestion controller over a 2430 relatively long period of time. Transport system implementations 2431 that map the requested capacity profile onto per-connection DSCP 2432 signaling without multiplexing SHOULD assign a DSCP Assured 2433 Forwarding (AF11,AF12,AF13,AF14) [RFC2597] PHB per Section 4.8 of 2434 [RFC4594]. 2436 The Capacity Profile for a selected protocol stack may be modified on 2437 a per-Message basis using the Transmission Profile Message Property; 2438 see Section 7.5.8. 2440 10.1.7. Bounds on Send or Receive Rate 2442 Name: max-send-rate / max-recv-rate 2444 Type: Numeric / Numeric 2445 Default: -1 / -1 (unlimited, for both values) 2447 This property specifies an upper-bound rate that a transfer is not 2448 expected to exceed (even if flow control and congestion control allow 2449 higher rates), and/or a lower-bound rate below which the application 2450 does not deem a data transfer useful. It is given in bits per 2451 second. The special value -1 indicates that no bound is specified. 2453 10.1.8. Read-only Connection Properties 2455 The following generic Connection Properties are read-only, i.e. they 2456 cannot be changed by an application. 2458 10.1.8.1. Maximum Message Size Concurrent with Connection Establishment 2460 Name: zero-rtt-msg-max-len 2462 Type: Integer 2464 This property represents the maximum Message size that can be sent 2465 before or during Connection establishment, see also Section 7.5.4. 2466 It is given in Bytes. 2468 10.1.8.2. Maximum Message Size Before Fragmentation or Segmentation 2470 Name: singular-transmission-msg-max-len 2472 Type: Integer 2474 This property, if applicable, represents the maximum Message size 2475 that can be sent without incurring network-layer fragmentation or 2476 transport layer segmentation at the sender. This property exposes 2477 the Maximum Packet Size (MPS) as described in Datagram PLPMTUD 2478 [I-D.ietf-tsvwg-datagram-plpmtud]. 2480 10.1.8.3. Maximum Message Size on Send 2482 Name: send-msg-max-len 2484 Type: Integer 2486 This property represents the maximum Message size that can be sent 2487 using a send operation. 2489 10.1.8.4. Maximum Message Size on Receive 2491 Name: recv-msg-max-len 2492 Type: Integer 2494 This numeric property represents the maximum Message size that can be 2495 received. 2497 10.2. TCP-specific Properties: User Timeout Option (UTO) 2499 These properties specify configurations for the User Timeout Option 2500 (UTO), in case TCP becomes the chosen transport protocol. 2501 Implementation is optional and of course only sensible if TCP is 2502 implemented in the transport system. 2504 These TCP-specific properties are included here because the feature 2505 "Suggest timeout to the peer" is part of the minimal set of transport 2506 services [I-D.ietf-taps-minset], where this feature was categorized 2507 as "functional". This means that when an implementation offers this 2508 feature, it has to expose an interface to it to the application. 2509 Otherwise, the implementation might violate assumptions by the 2510 application, which could cause the application to fail. 2512 All of the below properties are optional (e.g., it is possible to 2513 specify "User Timeout Enabled" as true, but not specify an Advertised 2514 User Timeout value; in this case, the TCP default will be used). 2516 10.2.1. Advertised User Timeout 2518 Name: tcp.user-timeout-value 2520 Type: Integer 2522 Default: the TCP default 2524 This time value is advertised via the TCP User Timeout Option (UTO) 2525 [RFC5482] at the remote endpoint to adapt its own "Timeout for 2526 aborting Connection" (see Section 10.1.4) value accordingly. 2528 10.2.2. User Timeout Enabled 2530 Name: tcp.user-timeout 2532 Type: Boolean 2534 Default: false 2536 This property controls whether the UTO option is enabled for a 2537 connection. This applies to both sending and receiving. 2539 10.2.3. Timeout Changeable 2541 Name: tcp.user-timeout-recv 2543 Type: Boolean 2545 Default: true 2547 This property controls whether the "Timeout for aborting Connection" 2548 (see Section 10.1.4) may be changed based on a UTO option received 2549 from the remote peer. This boolean becomes false when "Timeout for 2550 aborting Connection" (see Section 10.1.4) is used. 2552 10.3. Connection Lifecycle Events 2554 During the lifetime of a connection there are events that can occur 2555 when configured. 2557 10.3.1. Soft Errors 2559 Asynchronous introspection is also possible, via the SoftError Event. 2560 This event informs the application about the receipt and contents of 2561 an ICMP error message related to the Connection. This will only 2562 happen if the underlying protocol stack supports access to soft 2563 errors; however, even if the underlying stack supports it, there is 2564 no guarantee that a soft error will be signaled. 2566 Connection -> SoftError<> 2568 10.3.2. Excessive retransmissions 2570 This event notifies the application of excessive retransmissions, 2571 based on a configured threshold (see Section 10.1.1). This will only 2572 happen if the underlying protocol stack supports reliability and, 2573 with it, such notifications. 2575 Connection -> ExcessiveRetransmission<> 2577 11. Connection Termination 2579 Close terminates a Connection after satisfying all the requirements 2580 that were specified regarding the delivery of Messages that the 2581 application has already given to the transport system. For example, 2582 if reliable delivery was requested for a Message handed over before 2583 calling Close, the transport system will ensure that this Message is 2584 indeed delivered. If the Remote Endpoint still has data to send, it 2585 cannot be received after this call. 2587 Connection.Close() 2589 The Closed Event can inform the application that the Remote Endpoint 2590 has closed the Connection; however, there is no guarantee that a 2591 remote Close will indeed be signaled. 2593 Connection -> Closed<> 2595 Abort terminates a Connection without delivering remaining data: 2597 Connection.Abort() 2599 A ConnectionError informs the application that data to could not be 2600 delivered after a timeout, or the other side has aborted the 2601 Connection; however, there is no guarantee that an Abort will indeed 2602 be signaled. 2604 Connection -> ConnectionError 2606 12. Connection State and Ordering of Operations and Events 2608 As this interface is designed to be independent of an 2609 implementation's concurrency model, the details of how exactly 2610 actions are handled, and how events are dispatched, are 2611 implementation dependent. 2613 Each transition of connection state is associated with one of more 2614 events: 2616 * Ready<> occurs when a Connection created with Initiate() or 2617 InitiateWithSend() transitions to Established state. 2619 * ConnectionReceived<> occurs when a Connection created with 2620 Listen() transitions to Established state. 2622 * RendezvousDone<> occurs when a Connection created with 2623 Rendezvous() transitions to Established state. 2625 * Closed<> occurs when a Connection transitions to Closed state 2626 without error. 2628 * InitiateError<> occurs when a Connection created with Initiate() 2629 transitions from Establishing state to Closed state due to an 2630 error. 2632 * ConnectionError<> occurs when a Connection transitions to Closed 2633 state due to an error in all other circumstances. 2635 The interface provides the following guarantees about the ordering of 2636 operations: 2638 * Sent<> events will occur on a Connection in the order in which the 2639 Messages were sent (i.e., delivered to the kernel or to the 2640 network interface, depending on implementation). 2642 * Received<> will never occur on a Connection before it is 2643 Established; i.e. before a Ready<> event on that Connection, or a 2644 ConnectionReceived<> or RendezvousDone<> containing that 2645 Connection. 2647 * No events will occur on a Connection after it is Closed; i.e., 2648 after a Closed<> event, an InitiateError<> or ConnectionError<> on 2649 that connection. To ensure this ordering, Closed<> will not occur 2650 on a Connection while other events on the Connection are still 2651 locally outstanding (i.e., known to the interface and waiting to 2652 be dealt with by the application). ConnectionError<> may occur 2653 after Closed<>, but the interface must gracefully handle all cases 2654 where application ignores these errors. 2656 13. IANA Considerations 2658 RFC-EDITOR: Please remove this section before publication. 2660 This document has no Actions for IANA. Later versions of this 2661 document may create IANA registries for generic transport property 2662 names and transport property namespaces (see Section 4.2.1). 2664 14. Security Considerations 2666 This document describes a generic API for interacting with a 2667 transport services (TAPS) system. Part of this API includes 2668 configuration details for transport security protocols, as discussed 2669 in Section 5.3. It does not recommend use (or disuse) of specific 2670 algorithms or protocols. Any API-compatible transport security 2671 protocol should work in a TAPS system. Security consideration for 2672 these protocols should be discussed in the respective specifications. 2674 The desribed API is used to exchange information between an 2675 application and the transport system. While it is not necessarily 2676 expected that both systems are implemented by the same authority, it 2677 is expected that the transport system implementation is either 2678 provided as a library that is selected by the application from a 2679 trusted party, or that it is part of the operating system that the 2680 application also relies on for other tasks. 2682 In either case, the TAPS API is an internal interface that is used to 2683 change information locally between two systems. However, as the 2684 transport system is responsible for network communication, it is in 2685 the position to potentially share any information provided by the 2686 application with the network or another communication peer. Most of 2687 the information provided over the TAPS API are useful to configure 2688 and select protocols and paths and are not necessarily privacy 2689 sensitive. Still, there is some information that could be privacy 2690 sensitve because this might reveal usage characteristics and habits 2691 of the user of an application. 2693 Of course any communication over a network reveals usage 2694 characteristics, as all packets as well as their timing and size are 2695 part of the network-visible wire image [RFC8546]. However, the 2696 selection of a protocol and its configuration also impacts which 2697 information is visible, potentially in clear text, and which other 2698 enties can access it. In most cases information that is provided for 2699 protocol and path selection should not directly translate to 2700 information that is can be observed by network devices on the path. 2701 But there might be specific configuration information that are 2702 intended for path exposure, such as e.g. a DiffServ codepoint 2703 setting, that is either povided directly by the application or 2704 indirectly configured over a traffic profile. 2706 Further, applications should be aware that communication attempts can 2707 lead to more than one connection establishment. This is for example 2708 the case when the transport system also excecutes name resolution; or 2709 when support mechanisms such as TURN or ICE are used to establish 2710 connectivity; or if protocols or paths are raised; or if a path fails 2711 and fallback or re-establishment is supported in the transport 2712 system. 2714 These communication activities are not different from what is used 2715 today, however, the goal of a TAPS transport system is to support 2716 such mechanisms as a generic service within the transport layer. 2717 This enables applications to more dynamically benefit from 2718 innovations and new protocols in the transport system but at the same 2719 time may reduce transparency of the underlying communication actions 2720 to the application itself. The TAPS API is designed such that 2721 protocol and path selection can be limited to a small and controlled 2722 set if required by the application for functional or security 2723 purposes. Further, TAPS implementations should provide an interface 2724 to poll information about which protocol and path is currently in use 2725 as well as provide logging about the communication events of each 2726 connection. 2728 15. Acknowledgements 2730 This work has received funding from the European Union's Horizon 2020 2731 research and innovation programme under grant agreements No. 644334 2732 (NEAT) and No. 688421 (MAMI). 2734 This work has been supported by Leibniz Prize project funds of DFG - 2735 German Research Foundation: Gottfried Wilhelm Leibniz-Preis 2011 (FKZ 2736 FE 570/4-1). 2738 This work has been supported by the UK Engineering and Physical 2739 Sciences Research Council under grant EP/R04144X/1. 2741 This work has been supported by the Research Council of Norway under 2742 its "Toppforsk" programme through the "OCARINA" project. 2744 Thanks to Stuart Cheshire, Josh Graessley, David Schinazi, and Eric 2745 Kinnear for their implementation and design efforts, including Happy 2746 Eyeballs, that heavily influenced this work. Thanks to Laurent Chuat 2747 and Jason Lee for initial work on the Post Sockets interface, from 2748 which this work has evolved. Thanks to Maximilian Franke for asking 2749 good questions based on implementation experience and for 2750 contributing text, e.g., on multicast. 2752 16. References 2754 16.1. Normative References 2756 [I-D.ietf-taps-arch] 2757 Pauly, T., Trammell, B., Brunstrom, A., Fairhurst, G., 2758 Perkins, C., Tiesel, P., and C. Wood, "An Architecture for 2759 Transport Services", Work in Progress, Internet-Draft, 2760 draft-ietf-taps-arch-06, 23 December 2019, 2761 . 2764 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2765 Requirement Levels", BCP 14, RFC 2119, 2766 DOI 10.17487/RFC2119, March 1997, 2767 . 2769 [RFC4941] Narten, T., Draves, R., and S. Krishnan, "Privacy 2770 Extensions for Stateless Address Autoconfiguration in 2771 IPv6", RFC 4941, DOI 10.17487/RFC4941, September 2007, 2772 . 2774 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2775 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2776 May 2017, . 2778 [RFC8303] Welzl, M., Tuexen, M., and N. Khademi, "On the Usage of 2779 Transport Features Provided by IETF Transport Protocols", 2780 RFC 8303, DOI 10.17487/RFC8303, February 2018, 2781 . 2783 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2784 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2785 . 2787 16.2. Informative References 2789 [I-D.ietf-taps-impl] 2790 Brunstrom, A., Pauly, T., Enghardt, T., Grinnemo, K., 2791 Jones, T., Tiesel, P., Perkins, C., and M. Welzl, 2792 "Implementing Interfaces to Transport Services", Work in 2793 Progress, Internet-Draft, draft-ietf-taps-impl-05, 4 2794 November 2019, . 2797 [I-D.ietf-taps-minset] 2798 Welzl, M. and S. Gjessing, "A Minimal Set of Transport 2799 Services for End Systems", Work in Progress, Internet- 2800 Draft, draft-ietf-taps-minset-11, 27 September 2018, 2801 . 2804 [I-D.ietf-taps-transport-security] 2805 Enghardt, T., Pauly, T., Perkins, C., Rose, K., and C. 2806 Wood, "A Survey of the Interaction Between Security 2807 Protocols and Transport Services", Work in Progress, 2808 Internet-Draft, draft-ietf-taps-transport-security-11, 5 2809 March 2020, . 2812 [I-D.ietf-tsvwg-datagram-plpmtud] 2813 Fairhurst, G., Jones, T., Tuexen, M., Ruengeler, I., and 2814 T. Voelker, "Packetization Layer Path MTU Discovery for 2815 Datagram Transports", Work in Progress, Internet-Draft, 2816 draft-ietf-tsvwg-datagram-plpmtud-15, 24 February 2020, 2817 . 2820 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 2821 "Definition of the Differentiated Services Field (DS 2822 Field) in the IPv4 and IPv6 Headers", RFC 2474, 2823 DOI 10.17487/RFC2474, December 1998, 2824 . 2826 [RFC2597] Heinanen, J., Baker, F., Weiss, W., and J. Wroclawski, 2827 "Assured Forwarding PHB Group", RFC 2597, 2828 DOI 10.17487/RFC2597, June 1999, 2829 . 2831 [RFC2914] Floyd, S., "Congestion Control Principles", BCP 41, 2832 RFC 2914, DOI 10.17487/RFC2914, September 2000, 2833 . 2835 [RFC3246] Davie, B., Charny, A., Bennet, J.C.R., Benson, K., Le 2836 Boudec, J.Y., Courtney, W., Davari, S., Firoiu, V., and D. 2837 Stiliadis, "An Expedited Forwarding PHB (Per-Hop 2838 Behavior)", RFC 3246, DOI 10.17487/RFC3246, March 2002, 2839 . 2841 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 2842 A., Peterson, J., Sparks, R., Handley, M., and E. 2843 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 2844 DOI 10.17487/RFC3261, June 2002, 2845 . 2847 [RFC4594] Babiarz, J., Chan, K., and F. Baker, "Configuration 2848 Guidelines for DiffServ Service Classes", RFC 4594, 2849 DOI 10.17487/RFC4594, August 2006, 2850 . 2852 [RFC5245] Rosenberg, J., "Interactive Connectivity Establishment 2853 (ICE): A Protocol for Network Address Translator (NAT) 2854 Traversal for Offer/Answer Protocols", RFC 5245, 2855 DOI 10.17487/RFC5245, April 2010, 2856 . 2858 [RFC5482] Eggert, L. and F. Gont, "TCP User Timeout Option", 2859 RFC 5482, DOI 10.17487/RFC5482, March 2009, 2860 . 2862 [RFC5865] Baker, F., Polk, J., and M. Dolly, "A Differentiated 2863 Services Code Point (DSCP) for Capacity-Admitted Traffic", 2864 RFC 5865, DOI 10.17487/RFC5865, May 2010, 2865 . 2867 [RFC7478] Holmberg, C., Hakansson, S., and G. Eriksson, "Web Real- 2868 Time Communication Use Cases and Requirements", RFC 7478, 2869 DOI 10.17487/RFC7478, March 2015, 2870 . 2872 [RFC7556] Anipko, D., Ed., "Multiple Provisioning Domain 2873 Architecture", RFC 7556, DOI 10.17487/RFC7556, June 2015, 2874 . 2876 [RFC7657] Black, D., Ed. and P. Jones, "Differentiated Services 2877 (Diffserv) and Real-Time Communication", RFC 7657, 2878 DOI 10.17487/RFC7657, November 2015, 2879 . 2881 [RFC8084] Fairhurst, G., "Network Transport Circuit Breakers", 2882 BCP 208, RFC 8084, DOI 10.17487/RFC8084, March 2017, 2883 . 2885 [RFC8095] Fairhurst, G., Ed., Trammell, B., Ed., and M. Kuehlewind, 2886 Ed., "Services Provided by IETF Transport Protocols and 2887 Congestion Control Mechanisms", RFC 8095, 2888 DOI 10.17487/RFC8095, March 2017, 2889 . 2891 [RFC8260] Stewart, R., Tuexen, M., Loreto, S., and R. Seggelmann, 2892 "Stream Schedulers and User Message Interleaving for the 2893 Stream Control Transmission Protocol", RFC 8260, 2894 DOI 10.17487/RFC8260, November 2017, 2895 . 2897 [RFC8546] Trammell, B. and M. Kuehlewind, "The Wire Image of a 2898 Network Protocol", RFC 8546, DOI 10.17487/RFC8546, April 2899 2019, . 2901 [RFC8622] Bless, R., "A Lower-Effort Per-Hop Behavior (LE PHB) for 2902 Differentiated Services", RFC 8622, DOI 10.17487/RFC8622, 2903 June 2019, . 2905 [RFC8699] Islam, S., Welzl, M., and S. Gjessing, "Coupled Congestion 2906 Control for RTP Media", RFC 8699, DOI 10.17487/RFC8699, 2907 January 2020, . 2909 [TCP-COUPLING] 2910 "ctrlTCP: Reducing Latency through Coupled, Heterogeneous 2911 Multi-Flow TCP Congestion Control", IEEE INFOCOM Global 2912 Internet Symposium (GI) workshop (GI 2018) , 15 April 2913 2018. 2915 Appendix A. Convenience Functions 2916 A.1. Adding Preference Properties 2918 As Selection Properties of type "Preference" will be added to a 2919 TransportProperties object quite frequently, implementations should 2920 provide special actions for adding each preference level i.e, 2921 "TransportProperties.Add(some_property, avoid)" is equivalent to 2922 "TransportProperties.Avoid(some_property)": 2924 TransportProperties.Require(property) 2925 TransportProperties.Prefer(property) 2926 TransportProperties.Ignore(property) 2927 TransportProperties.Avoid(property) 2928 TransportProperties.Prohibit(property) 2929 TransportProperties.Default(property) 2931 A.2. Transport Property Profiles 2933 To ease the use of the interface specified by this document, 2934 implementations should provide a mechanism to create Transport 2935 Property objects (see Section 5.2) that are pre-configured with 2936 frequently used sets of properties. Implementations should at least 2937 offer short-hands to specify the following property profiles: 2939 A.2.1. reliable-inorder-stream 2941 This profile provides reliable, in-order transport service with 2942 congestion control. An example of a protocol that provides this 2943 service is TCP. It should consist of the following properties: 2945 +-------------------------+---------+ 2946 | Property | Value | 2947 +=========================+=========+ 2948 | reliability | require | 2949 +-------------------------+---------+ 2950 | preserve-order | require | 2951 +-------------------------+---------+ 2952 | congestion-control | require | 2953 +-------------------------+---------+ 2954 | preserve-msg-boundaries | ignore | 2955 +-------------------------+---------+ 2957 Table 2 2959 A.2.2. reliable-message 2961 This profile provides message-preserving, reliable, in-order 2962 transport service with congestion control. An example of a protocol 2963 that provides this service is SCTP. It should consist of the 2964 following properties: 2966 +-------------------------+---------+ 2967 | Property | Value | 2968 +=========================+=========+ 2969 | reliability | require | 2970 +-------------------------+---------+ 2971 | preserve-order | require | 2972 +-------------------------+---------+ 2973 | congestion-control | require | 2974 +-------------------------+---------+ 2975 | preserve-msg-boundaries | require | 2976 +-------------------------+---------+ 2978 Table 3 2980 A.2.3. unreliable-datagram 2982 This profile provides unreliable datagram transport service. An 2983 example of a protocol that provides this service is UDP. It should 2984 consist of the following properties: 2986 +-------------------------+---------+ 2987 | Property | Value | 2988 +=========================+=========+ 2989 | reliability | ignore | 2990 +-------------------------+---------+ 2991 | preserve-order | ignore | 2992 +-------------------------+---------+ 2993 | congestion-control | ignore | 2994 +-------------------------+---------+ 2995 | preserve-msg-boundaries | require | 2996 +-------------------------+---------+ 2997 | idempotent | true | 2998 +-------------------------+---------+ 3000 Table 4 3002 Applications that choose this Transport Property Profile for latency 3003 reasons should also consider setting the Capacity Profile Property, 3004 see Section 10.1.6 accordingly and my benefit from controlling 3005 checksum coverage, see Section 5.2.7 and Section 5.2.8. 3007 Appendix B. Relationship to the Minimal Set of Transport Services for 3008 End Systems 3010 [I-D.ietf-taps-minset] identifies a minimal set of transport services 3011 that end systems should offer. These services make all non-security- 3012 related transport features of TCP, MPTCP, UDP, UDP-Lite, SCTP and 3013 LEDBAT available that 1) require interaction with the application, 3014 and 2) do not get in the way of a possible implementation over TCP 3015 (or, with limitations, UDP). The following text explains how this 3016 minimal set is reflected in the present API. For brevity, it is 3017 based on the list in Section 4.1 of [I-D.ietf-taps-minset], updated 3018 according to the discussion in Section 5 of [I-D.ietf-taps-minset]. 3019 This list is a subset of the transport features in Appendix A of 3020 [I-D.ietf-taps-minset], which refers to the primitives in "pass 2" 3021 (Section 4) of [RFC8303] for further details on the implementation 3022 with TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT. 3024 * Connect: "Initiate" Action (Section 6.1). 3026 * Listen: "Listen" Action (Section 6.2). 3028 * Specify number of attempts and/or timeout for the first 3029 establishment message: "timeout" parameter of "Initiate" 3030 (Section 6.1) or "InitiateWithSend" Action (Section 7.8). 3032 * Disable MPTCP: "Parallel Use of Multiple Paths" Property 3033 (Section 5.2.13). 3035 * Hand over a message to reliably transfer (possibly multiple times) 3036 before connection establishment: "InitiateWithSend" Action 3037 (Section 7.8). 3039 * Change timeout for aborting connection (using retransmit limit or 3040 time value): "Timeout for Aborting Connection" property, using a 3041 time value (Section 10.1.4). 3043 * Timeout event when data could not be delivered for too long: 3044 "ConnectionError" Event (Section 11). 3046 * Suggest timeout to the peer: "TCP-specific Property: User Timeout" 3047 (Section 10.2). 3049 * Notification of Excessive Retransmissions (early warning below 3050 abortion threshold): "Notification of excessive retransmissions" 3051 property (Section 5.2.15). 3053 * Notification of ICMP error message arrival: "Notification of ICMP 3054 soft error message arrival" property (Section 5.2.16). 3056 * Choose a scheduler to operate between streams of an association: 3057 "Connection Group Transmission Scheduler" property 3058 (Section 10.1.5). 3060 * Configure priority or weight for a scheduler: "Priority 3061 (Connection)" property (Section 10.1.3). 3063 * "Specify checksum coverage used by the sender" and "Disable 3064 checksum when sending": "Corruption Protection Length" property 3065 (Section 7.5.6) and "Full Checksum Coverage on Sending" property 3066 (Section 5.2.7). 3068 * "Specify minimum checksum coverage required by receiver" and 3069 "Disable checksum requirement when receiving": "Required Minimum 3070 Corruption Protection Coverage for Receiving" property 3071 (Section 10.1.2) and "Full Checksum Coverage on Receiving" 3072 property (Section 5.2.8). 3074 * "Specify DF" field and "Request not to bundle messages": the 3075 "Singular Transmission" Message Property combines both of these 3076 requests, i.e. if a request not to bundle messages is made, this 3077 also turns off fragmentation (i.e., sets DF=1) in case of 3078 protocols that allow this (only UDP and UDP-Lite, which cannot 3079 bundle messages anyway) (Section 7.5.9). 3081 * Get max. transport-message size that may be sent using a non- 3082 fragmented IP packet from the configured interface: "Maximum 3083 Message Size Before Fragmentation or Segmentation" property 3084 (Section 10.1.8.2). 3086 * Get max. transport-message size that may be received from the 3087 configured interface: "Maximum Message Size on Receive" property 3088 (Section 10.1.8.4). 3090 * Obtain ECN field: "ECN" is a defined UDP(-Lite)-specific read-only 3091 Message Property of the MessageContext object (Section 8.3.1). 3093 * "Specify DSCP field", "Disable Nagle algorithm", "Enable and 3094 configure a 'Low Extra Delay Background Transfer'": as suggested 3095 in Section 5.5 of [I-D.ietf-taps-minset], these transport features 3096 are collectively offered via the "Capacity Profile" property 3097 (Section 10.1.6). Per-Message control is offered via the "Message 3098 Capacity Profile Override" property (Section 7.5.8). 3100 * Close after reliably delivering all remaining data, causing an 3101 event informing the application on the other side: this is offered 3102 by the "Close" Action with slightly changed semantics in line with 3103 the discussion in Section 5.2 of [I-D.ietf-taps-minset] 3104 (Section 11). 3106 * "Abort without delivering remaining data, causing an event 3107 informing the application on the other side" and "Abort without 3108 delivering remaining data, not causing an event informing the 3109 application on the other side": this is offered by the "Abort" 3110 action without promising that this is signaled to the other side. 3111 If it is, a "ConnectionError" Event will fire at the peer 3112 (Section 11). 3114 * "Reliably transfer data, with congestion control", "Reliably 3115 transfer a message, with congestion control" and "Unreliably 3116 transfer a message": data is transferred via the "Send" action 3117 (Section 7). Reliability is controlled via the "Reliable Data 3118 Transfer (Connection)" (Section 5.2.1) property and the "Reliable 3119 Data Transfer (Message)" Message Property (Section 7.5.7). 3120 Transmitting data as a message or without delimiters is controlled 3121 via Message Framers (Section 9). The choice of congestion control 3122 is provided via the "Congestion control" property (Section 5.2.9). 3124 * Configurable Message Reliability: the "Lifetime" Message Property 3125 implements a time-based way to configure message reliability 3126 (Section 7.5.1). 3128 * "Ordered message delivery (potentially slower than unordered)" and 3129 "Unordered message delivery (potentially faster than ordered)": 3130 these two transport features are controlled via the Message 3131 Property "Ordered" (Section 7.5.3). 3133 * Request not to delay the acknowledgement (SACK) of a message: 3134 should the protocol support it, this is one of the transport 3135 features the transport system can apply when an application uses 3136 the "Capacity Profile" Property (Section 10.1.6) or the "Message 3137 Capacity Profile Override" Message Property (Section 7.5.8) with 3138 value "Low Latency/Interactive". 3140 * Receive data (with no message delimiting): "Received" Event 3141 (Section 8.2.1). See Section 9 for handling Message framing in 3142 situations where the Protocol Stack only provides a byte-stream 3143 transport. 3145 * Receive a message: "Received" Event (Section 8.2.1), using Message 3146 Framers (Section 9). 3148 * Information about partial message arrival: "ReceivedPartial" Event 3149 (Section 8.2.2). 3151 * Notification of send failures: "Expired" Event (Section 7.3.2) and 3152 "SendError" Event (Section 7.3.3). 3154 * Notification that the stack has no more user data to send: 3155 applications can obtain this information via the "Sent" Event 3156 (Section 7.3.1). 3158 * Notification to a receiver that a partial message delivery has 3159 been aborted: "ReceiveError" Event (Section 8.2.3). 3161 Authors' Addresses 3163 Brian Trammell (editor) 3164 Google 3165 Gustav-Gull-Platz 1 3166 CH- 8004 Zurich 3167 Switzerland 3169 Email: ietf@trammell.ch 3171 Michael Welzl (editor) 3172 University of Oslo 3173 PO Box 1080 Blindern 3174 0316 Oslo 3175 Norway 3177 Email: michawe@ifi.uio.no 3179 Theresa Enghardt 3180 TU Berlin 3181 Marchstrasse 23 3182 10587 Berlin 3183 Germany 3185 Email: theresa@inet.tu-berlin.de 3187 Godred Fairhurst 3188 University of Aberdeen 3189 Fraser Noble Building 3190 Aberdeen, AB24 3UE 3192 Email: gorry@erg.abdn.ac.uk 3193 URI: http://www.erg.abdn.ac.uk/ 3194 Mirja Kuehlewind 3195 Ericsson 3196 Ericsson-Allee 1 3197 Herzogenrath 3198 Germany 3200 Email: mirja.kuehlewind@ericsson.com 3202 Colin Perkins 3203 University of Glasgow 3204 School of Computing Science 3205 Glasgow G12 8QQ 3206 United Kingdom 3208 Email: csp@csperkins.org 3210 Philipp S. Tiesel 3211 TU Berlin 3212 Einsteinufer 25 3213 10587 Berlin 3214 Germany 3216 Email: philipp@tiesel.net 3218 Chris Wood 3219 Apple Inc. 3220 One Apple Park Way 3221 Cupertino, California 95014, 3222 United States of America 3224 Email: cawood@apple.com 3226 Tommy Pauly 3227 Apple Inc. 3228 One Apple Park Way 3229 Cupertino, California 95014, 3230 United States of America 3232 Email: tpauly@apple.com