idnits 2.17.1 draft-ietf-taps-interface-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 12 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 04, 2019) is 1635 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) == Unused Reference: 'I-D.ietf-tsvwg-rtcweb-qos' is defined on line 2496, but no explicit reference was found in the text == Outdated reference: A later version (-19) exists of draft-ietf-taps-arch-04 ** Downref: Normative reference to an Informational RFC: RFC 8303 == Outdated reference: A later version (-18) exists of draft-ietf-taps-impl-04 == Outdated reference: A later version (-12) exists of draft-ietf-taps-transport-security-09 -- Obsolete informational reference (is this intentional?): RFC 793 (Obsoleted by RFC 9293) -- Obsolete informational reference (is this intentional?): RFC 5245 (Obsoleted by RFC 8445, RFC 8839) Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 TAPS Working Group B. Trammell, Ed. 3 Internet-Draft Google 4 Intended status: Standards Track M. Welzl, Ed. 5 Expires: May 7, 2020 University of Oslo 6 T. Enghardt 7 TU Berlin 8 G. Fairhurst 9 University of Aberdeen 10 M. Kuehlewind 11 ETH Zurich 12 C. Perkins 13 University of Glasgow 14 P. Tiesel 15 TU Berlin 16 C. Wood 17 T. Pauly 18 Apple Inc. 19 November 04, 2019 21 An Abstract Application Layer Interface to Transport Services 22 draft-ietf-taps-interface-05 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 May 7, 2020. 51 Copyright Notice 53 Copyright (c) 2019 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 58 (https://trustee.ietf.org/license-info) in effect on the date of 59 publication of this document. Please review these documents 60 carefully, as they describe your rights and restrictions with respect 61 to this document. Code Components extracted from this document must 62 include Simplified BSD License text as described in Section 4.e of 63 the Trust Legal Provisions and are provided without warranty as 64 described in the Simplified BSD License. 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 69 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 5 70 3. Interface Design Principles . . . . . . . . . . . . . . . . . 6 71 4. API Summary . . . . . . . . . . . . . . . . . . . . . . . . . 7 72 4.1. Usage Examples . . . . . . . . . . . . . . . . . . . . . 8 73 4.1.1. Server Example . . . . . . . . . . . . . . . . . . . 8 74 4.1.2. Client Example . . . . . . . . . . . . . . . . . . . 9 75 4.1.3. Peer Example . . . . . . . . . . . . . . . . . . . . 10 76 4.2. Transport Properties . . . . . . . . . . . . . . . . . . 11 77 4.2.1. Transport Property Names . . . . . . . . . . . . . . 12 78 4.2.2. Transport Property Types . . . . . . . . . . . . . . 13 79 4.3. Scope of the Interface Definition . . . . . . . . . . . . 13 80 5. Pre-Establishment Phase . . . . . . . . . . . . . . . . . . . 14 81 5.1. Specifying Endpoints . . . . . . . . . . . . . . . . . . 15 82 5.2. Specifying Transport Properties . . . . . . . . . . . . . 16 83 5.2.1. Reliable Data Transfer (Connection) . . . . . . . . . 18 84 5.2.2. Preservation of Message Boundaries . . . . . . . . . 18 85 5.2.3. Configure Per-Message Reliability . . . . . . . . . . 18 86 5.2.4. Preservation of Data Ordering . . . . . . . . . . . . 18 87 5.2.5. Use 0-RTT Session Establishment with an Idempotent 88 Message . . . . . . . . . . . . . . . . . . . . . . . 19 89 5.2.6. Multistream Connections in Group . . . . . . . . . . 19 90 5.2.7. Full Checksum Coverage on Sending . . . . . . . . . . 19 91 5.2.8. Full Checksum Coverage on Receiving . . . . . . . . . 19 92 5.2.9. Congestion control . . . . . . . . . . . . . . . . . 19 93 5.2.10. Interface Instance or Type . . . . . . . . . . . . . 20 94 5.2.11. Provisioning Domain Instance or Type . . . . . . . . 21 95 5.2.12. Parallel Use of Multiple Paths . . . . . . . . . . . 21 96 5.2.13. Direction of communication . . . . . . . . . . . . . 22 97 5.2.14. Notification of excessive retransmissions . . . . . . 22 98 5.2.15. Notification of ICMP soft error message arrival . . . 22 99 5.3. Specifying Security Parameters and Callbacks . . . . . . 22 100 5.3.1. Pre-Connection Parameters . . . . . . . . . . . . . . 23 101 5.3.2. Connection Establishment Callbacks . . . . . . . . . 24 102 6. Establishing Connections . . . . . . . . . . . . . . . . . . 24 103 6.1. Active Open: Initiate . . . . . . . . . . . . . . . . . . 24 104 6.2. Passive Open: Listen . . . . . . . . . . . . . . . . . . 26 105 6.3. Peer-to-Peer Establishment: Rendezvous . . . . . . . . . 27 106 6.4. Connection Groups . . . . . . . . . . . . . . . . . . . . 28 107 7. Sending Data . . . . . . . . . . . . . . . . . . . . . . . . 29 108 7.1. Basic Sending . . . . . . . . . . . . . . . . . . . . . . 30 109 7.2. Sending Replies . . . . . . . . . . . . . . . . . . . . . 30 110 7.3. Send Events . . . . . . . . . . . . . . . . . . . . . . . 31 111 7.3.1. Sent . . . . . . . . . . . . . . . . . . . . . . . . 31 112 7.3.2. Expired . . . . . . . . . . . . . . . . . . . . . . . 31 113 7.3.3. SendError . . . . . . . . . . . . . . . . . . . . . . 32 114 7.4. Message Properties . . . . . . . . . . . . . . . . . . . 32 115 7.4.1. Lifetime . . . . . . . . . . . . . . . . . . . . . . 33 116 7.4.2. Priority . . . . . . . . . . . . . . . . . . . . . . 33 117 7.4.3. Ordered . . . . . . . . . . . . . . . . . . . . . . . 34 118 7.4.4. Idempotent . . . . . . . . . . . . . . . . . . . . . 34 119 7.4.5. Final . . . . . . . . . . . . . . . . . . . . . . . . 34 120 7.4.6. Corruption Protection Length . . . . . . . . . . . . 35 121 7.4.7. Reliable Data Transfer (Message) . . . . . . . . . . 35 122 7.4.8. Message Capacity Profile Override . . . . . . . . . . 36 123 7.4.9. Singular Transmission . . . . . . . . . . . . . . . . 36 124 7.5. Partial Sends . . . . . . . . . . . . . . . . . . . . . . 37 125 7.6. Batching Sends . . . . . . . . . . . . . . . . . . . . . 37 126 7.7. Send on Active Open: InitiateWithSend . . . . . . . . . . 38 127 8. Receiving Data . . . . . . . . . . . . . . . . . . . . . . . 38 128 8.1. Enqueuing Receives . . . . . . . . . . . . . . . . . . . 38 129 8.2. Receive Events . . . . . . . . . . . . . . . . . . . . . 39 130 8.2.1. Received . . . . . . . . . . . . . . . . . . . . . . 39 131 8.2.2. ReceivedPartial . . . . . . . . . . . . . . . . . . . 40 132 8.2.3. ReceiveError . . . . . . . . . . . . . . . . . . . . 40 133 8.3. Receive Message Properties . . . . . . . . . . . . . . . 41 134 8.3.1. ECN . . . . . . . . . . . . . . . . . . . . . . . . . 41 135 8.3.2. Early Data . . . . . . . . . . . . . . . . . . . . . 41 136 8.3.3. Receiving Final Messages . . . . . . . . . . . . . . 41 137 9. Message Contexts . . . . . . . . . . . . . . . . . . . . . . 42 138 10. Message Framers . . . . . . . . . . . . . . . . . . . . . . . 42 139 10.1. Adding Message Framers to Connections . . . . . . . . . 43 140 10.2. Framing Meta-Data . . . . . . . . . . . . . . . . . . . 43 141 11. Managing Connections . . . . . . . . . . . . . . . . . . . . 44 142 11.1. Generic Connection Properties . . . . . . . . . . . . . 45 143 11.1.1. Retransmission Threshold Before Excessive 144 Retransmission Notification . . . . . . . . . . . . 46 146 11.1.2. Required Minimum Corruption Protection Coverage for 147 Receiving . . . . . . . . . . . . . . . . . . . . . 46 148 11.1.3. Priority (Connection) . . . . . . . . . . . . . . . 46 149 11.1.4. Timeout for Aborting Connection . . . . . . . . . . 46 150 11.1.5. Connection Group Transmission Scheduler . . . . . . 47 151 11.1.6. Maximum Message Size Concurrent with Connection 152 Establishment . . . . . . . . . . . . . . . . . . . 47 153 11.1.7. Maximum Message Size Before Fragmentation or 154 Segmentation . . . . . . . . . . . . . . . . . . . . 47 155 11.1.8. Maximum Message Size on Send . . . . . . . . . . . . 47 156 11.1.9. Maximum Message Size on Receive . . . . . . . . . . 48 157 11.1.10. Capacity Profile . . . . . . . . . . . . . . . . . . 48 158 11.1.11. Bounds on Send or Receive Rate . . . . . . . . . . . 49 159 11.1.12. TCP-specific Property: User Timeout . . . . . . . . 50 160 11.2. Soft Errors . . . . . . . . . . . . . . . . . . . . . . 50 161 11.3. Excessive retransmissions . . . . . . . . . . . . . . . 51 162 12. Connection Termination . . . . . . . . . . . . . . . . . . . 51 163 13. Connection State and Ordering of Operations and Events . . . 51 164 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 52 165 15. Security Considerations . . . . . . . . . . . . . . . . . . . 53 166 16. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 53 167 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 53 168 17.1. Normative References . . . . . . . . . . . . . . . . . . 53 169 17.2. Informative References . . . . . . . . . . . . . . . . . 54 170 Appendix A. Convenience Functions . . . . . . . . . . . . . . . 56 171 A.1. Adding Preference Properties . . . . . . . . . . . . . . 56 172 A.2. Transport Property Profiles . . . . . . . . . . . . . . . 56 173 A.2.1. reliable-inorder-stream . . . . . . . . . . . . . . . 57 174 A.2.2. reliable-message . . . . . . . . . . . . . . . . . . 57 175 A.2.3. unreliable-datagram . . . . . . . . . . . . . . . . . 57 176 Appendix B. Additional Properties . . . . . . . . . . . . . . . 58 177 B.1. Experimental Transport Properties . . . . . . . . . . . . 58 178 B.1.1. Cost Preferences . . . . . . . . . . . . . . . . . . 59 179 Appendix C. Sample API definition in Go . . . . . . . . . . . . 59 180 Appendix D. Relationship to the Minimal Set of Transport 181 Services for End Systems . . . . . . . . . . . . . . 59 182 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 62 184 1. Introduction 186 The BSD Unix Sockets API's SOCK_STREAM abstraction, by bringing 187 network sockets into the UNIX programming model, allowing anyone who 188 knew how to write programs that dealt with sequential-access files to 189 also write network applications, was a revolution in simplicity. The 190 simplicity of this API is a key reason the Internet won the protocol 191 wars [PROTOCOL-WARS] of the 1980s. SOCK_STREAM is tied to the 192 Transmission Control Protocol (TCP), specified in 1981 [RFC0793]. 193 TCP has scaled remarkably well over the past three and a half 194 decades, but its total ubiquity has hidden an uncomfortable fact: the 195 network is not really a file, and stream abstractions are too 196 simplistic for many modern application programming models. 198 In the meantime, the nature of Internet access, and the variety of 199 Internet transport protocols, is evolving. The challenges that new 200 protocols and access paradigms present to the sockets API and to 201 programming models based on them inspire the design principles of a 202 new approach, which we outline in Section 3. 204 This document builds a modern abstract programming interface atop the 205 high-level architecture for transport services defined in 206 [I-D.ietf-taps-arch]. It derives specific path and protocol 207 selection properties and supported transport features from the 208 analysis provided in [RFC8095], [I-D.ietf-taps-minset], and 209 [I-D.ietf-taps-transport-security]. 211 2. Terminology and Notation 213 This API is described in terms of Objects, which an application can 214 interact with; Actions the application can perform on these Objects; 215 Events, which an Object can send to an application asynchronously; 216 and Parameters associated with these Actions and Events. 218 The following notations, which can be combined, are used in this 219 document: 221 o An Action creates an Object: 223 Object := Action() 225 o An Action creates an array of Objects: 227 []Object := Action() 229 o An Action is performed on an Object: 231 Object.Action() 233 o An Object sends an Event: 235 Object -> Event<> 237 o An Action takes a set of Parameters; an Event contains a set of 238 Parameters. Action and Event parameters whose names are suffixed 239 with a question mark are optional. 241 Action(param0, param1?, ...) / Event 242 Actions associated with no Object are Actions on the abstract 243 interface itself; they are equivalent to Actions on a per-application 244 global context. 246 How these abstract concepts map into concrete implementations of this 247 API in a given language on a given platform is largely dependent on 248 the features of the language and the platform. Actions could be 249 implemented as functions or method calls, for instance, and Events 250 could be implemented via callbacks, communicating sequential 251 processes, or other asynchronous calling conventions. The method for 252 dispatching and handling Events is an implementation detail, with the 253 caveat that the interface for receiving Messages must require the 254 application to invoke the Connection.Receive() Action once per 255 Message to be received (see Section 8). 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. Interface Design Principles 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 o 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 o Message-orientation, as opposed to stream-orientation, using 289 application-assisted framing and deframing where the underlying 290 transport does not provide these; 292 o 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 o Explicit support for security properties as first-order transport 299 features, and for long-term caching of cryptographic identities 300 and parameters for associations among endpoints; and 302 o Explicit support for multistreaming and multipath transport 303 protocols, and the grouping of related Connections into Connection 304 Groups through cloning of Connections, to allow applications to 305 take full advantage of new transport protocols supporting these 306 features. 308 4. API Summary 310 The Transport Services Interface is the basic common abstract 311 application programming interface to the Transport Services 312 Architecture defined in the TAPS Architecture [I-D.ietf-taps-arch]. 314 An application primarily interacts with this interface through two 315 Objects: Preconnections and Connections. A Preconnection represents 316 a set of properties and constraints on the selection and 317 configuration of paths and protocols to establish a Connection with a 318 remote Endpoint. A Connection represents a transport Protocol Stack 319 on which data can be sent to and/or received from a remote Endpoint 320 (i.e., depending on the kind of transport, connections can be bi- 321 directional or unidirectional). Connections can be created from 322 Preconnections in three ways: by initiating the Preconnection (i.e., 323 actively opening, as in a client), through listening on the 324 Preconnection (i.e., passively opening, as in a server), or 325 rendezvousing on the Preconnection (i.e. peer to peer 326 establishment). 328 Once a Connection is established, data can be sent on it in the form 329 of Messages. The interface supports the preservation of message 330 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 a callback registered by the application. Errors and other 334 notifications also happen asynchronously on the Connection. 336 Section 5, Section 6, Section 7, Section 8, and Section 12 describe 337 the details of application interaction with Objects through Actions 338 and Events in each phase of a Connection, following the phases 339 described in [I-D.ietf-taps-arch]. 341 4.1. Usage Examples 343 The following usage examples illustrate how an application might use 344 a Transport Services Interface to: 346 o Act as a server, by listening for incoming connections, receiving 347 requests, and sending responses, see Section 4.1.1. 349 o Act as a client, by connecting to a remote endpoint using 350 Initiate, sending requests, and receiving responses, see 351 Section 4.1.2. 353 o Act as a peer, by connecting to a remote endpoint using Rendezvous 354 while simultaneously waiting for incoming Connections, sending 355 Messages, and receiving Messages, see Section 4.1.3. 357 The examples in this section presume that a transport protocol is 358 available between the endpoints that provides Reliable Data Transfer, 359 Preservation of data ordering, and Preservation of Message 360 Boundaries. In this case, the application can choose to receive only 361 complete messages. 363 If none of the available transport protocols provides Preservation of 364 Message Boundaries, but there is a transport protocol that provides a 365 reliable ordered byte stream, an application may receive this byte 366 stream as partial Messages and transform it into application-layer 367 Messages. Alternatively, an application may provide a Message 368 Framer, which can transform a byte stream into a sequence of Messages 369 (Section 10). 371 4.1.1. Server Example 373 This is an example of how an application might listen for incoming 374 Connections using the Transport Services Interface, receive a 375 request, and send a response. 377 LocalSpecifier := NewLocalEndpoint() 378 LocalSpecifier.WithInterface("any") 379 LocalSpecifier.WithService("https") 381 TransportProperties := NewTransportProperties() 382 TransportProperties.Require(preserve-msg-boundaries) 383 // Reliable Data Transfer and Preserve Order are Required by default 385 SecurityParameters := NewSecurityParameters() 386 SecurityParameters.AddIdentity(identity) 387 SecurityParameters.AddPrivateKey(privateKey, publicKey) 389 // Specifying a remote endpoint is optional when using Listen() 390 Preconnection := NewPreconnection(LocalSpecifier, 391 None, 392 TransportProperties, 393 SecurityParameters) 395 Listener := Preconnection.Listen() 397 Listener -> ConnectionReceived 399 // Only receive complete messages 400 Connection.Receive() 402 Connection -> Received(messageDataRequest, messageContext) 404 Connection.Send(messageDataResponse) 406 Connection.Close() 408 // Stop listening for incoming Connections 409 Listener.Stop() 411 4.1.2. Client Example 413 This is an example of how an application might connect to a remote 414 application using the Transport Services Interface, send a request, 415 and receive a response. 417 RemoteSpecifier := NewRemoteEndpoint() 418 RemoteSpecifier.WithHostname("example.com") 419 RemoteSpecifier.WithService("https") 421 TransportProperties := NewTransportProperties() 422 TransportProperties.Require(preserve-msg-boundaries) 423 // Reliable Data Transfer and Preserve Order are Required by default 425 SecurityParameters := NewSecurityParameters() 426 TrustCallback := New Callback({ 427 // Verify identity of the remote endpoint, return the result 428 }) 429 SecurityParameters.SetTrustVerificationCallback(TrustCallback) 431 // Specifying a local endpoint is optional when using Initiate() 432 Preconnection := NewPreconnection(None, 433 RemoteSpecifier, 434 TransportPreperties, 435 SecurityParameters) 437 Connection := Preconnection.Initiate() 439 Connection -> Ready<> 441 Connection.Send(messageDataRequest) 443 // Only receive complete messages 444 Connection.Receive() 446 Connection -> Received(messageDataResponse, messageContext) 448 Connection.Close() 450 4.1.3. Peer Example 452 This is an example of how an application might establish a connection 453 with a peer using Rendezvous(), send a Message, and receive a 454 Message. 456 LocalSpecifier := NewLocalEndpoint() 457 LocalSpecifier.WithPort(9876) 459 RemoteSpecifier := NewRemoteEndpoint() 460 RemoteSpecifier.WithHostname("example.com") 461 RemoteSpecifier.WithPort(9877) 463 TransportProperties := NewTransportProperties() 464 TransportProperties.Require(preserve-msg-boundaries) 465 // Reliable Data Transfer and Preserve Order are Required by default 467 SecurityParameters := NewSecurityParameters() 468 SecurityParameters.AddIdentity(identity) 469 SecurityParameters.AddPrivateKey(privateKey, publicKey) 471 TrustCallback := New Callback({ 472 // Verify identity of the remote endpoint, return the result 473 }) 474 SecurityParameters.SetTrustVerificationCallback(trustCallback) 476 // Both local and remote endpoint must be specified 477 Preconnection := NewPreconnection(LocalSpecifier, 478 RemoteSpecifier, 479 TransportPreperties, 480 SecurityParameters) 482 Preconnection.Rendezvous() 484 Preconnection -> RendezvousDone 486 Connection.Send(messageDataRequest) 488 // Only receive complete messages 489 Connection.Receive() 491 Connection -> Received(messageDataResponse, messageContext) 493 Connection.Close() 495 4.2. Transport Properties 497 Each application using the Transport Services Interface declares its 498 preferences for how the transport service should operate using 499 properties at each stage of the lifetime of a connection using 500 Transport Properties, as defined in [I-D.ietf-taps-arch]. 502 Transport Properties are divided into Selection, Connection, and 503 Message Properties. During pre-establishment, Selection Properties 504 (see Section 5.2) are used to specify which paths and protocol stacks 505 can be used and are preferred by the application, and Connection 506 Properties (see Section 11.1) can be used to influence decisions made 507 during establishment and to fine-tune the eventually established 508 connection. These Connection Properties can also be used later, to 509 monitor and fine-tune established connections. The behavior of the 510 selected protocol stack(s) when sending Messages is controlled by 511 Message Properties (see Section 7.4). 513 All Transport Properties, regardless of the phase in which they are 514 used, are organized within a single namespace. This enables setting 515 them as defaults in earlier stages and querying them in later stages: 517 o Connection Properties can be set on Preconnections 519 o Message Properties can be set on Preconnections and Connections 521 o The effect of Selection Properties can be queried on Connections 522 and Messages 524 Note that Configuring Connection Properties and Message Properties on 525 Preconnections is preferred over setting them later. Early 526 specification of Connection Properties allows their use as additional 527 input to the selection process. Protocol Specific Properties, see 528 Section 4.2.1, should not be used as an input to the selection 529 process. 531 4.2.1. Transport Property Names 533 Transport Properties are referred to by property names. These names 534 are lower-case strings whereby words are separated by hyphens. These 535 names serve two purposes: 537 o Allow different components of a TAPS implementation to pass 538 Transport Properties, e.g., between a language frontend and a 539 policy manager, or as a representation of properties retrieved 540 from a file or other storage. 542 o Make code of different TAPS implementations look similar. 544 Transport Property Names are hierarchically organized in the form 545 [.]. 547 o The Namespace part is empty for well known, generic properties, 548 i.e., for properties that are not specific to a protocol and are 549 defined in an RFC. 551 o Protocol Specific Properties must use the protocol acronym as 552 Namespace, e.g., "tcp" for TCP specific Transport Properties. For 553 IETF protocols, property names under these namespaces should be 554 defined in an RFC. 556 o Vendor or implementation specific properties must use a a string 557 identifying the vendor or implementation as Namespace. 559 4.2.2. Transport Property Types 561 Transport Properties can have one of a set of data types: 563 o Boolean: can take the values "true" and "false"; representation is 564 implementation-dependent. 566 o Integer: can take positive or negative numeric integer values; 567 range and representation is implementation-dependent. 569 o Numeric: can take positive or negative numeric values; range and 570 representation is implementation-dependent. 572 o Enumeration: can take one value of a finite set of values, 573 dependent on the property itself. The representation is 574 implementation dependent; however, implementations MUST provide a 575 method for the application to determine the entire set of possible 576 values for each property. 578 o Preference: can take one of five values (Prohibit, Avoid, Ignore, 579 Prefer, Require) for the level of preference of a given property 580 during protocol selection; see Section 5.2. 582 4.3. Scope of the Interface Definition 584 This document defines a language- and platform-independent interface 585 to a Transport Services system. Given the wide variety of languages 586 and language conventions used to write applications that use the 587 transport layer to connect to other applications over the Internet, 588 this independence makes this interface necessarily abstract. 590 There is no interoperability benefit in tightly defining how the 591 interface is presented to application programmers across diverse 592 platforms. However, maintaining the "shape" of the abstract 593 interface across these platforms reduces the effort for programmers 594 who learn the transport services interface to then apply their 595 knowledge across multiple platforms. 597 We therefore make the following recommendations: 599 o Actions, Events, and Errors in implementations of this interface 600 SHOULD use the names given for them in the document, subject to 601 capitalization, punctuation, and other typographic conventions in 602 the language of the implementation, unless the implementation 603 itself uses different names for substantially equivalent objects 604 for networking by convention. 606 o Implementations of this interface SHOULD implement each Selection 607 Property, Connection Property, and Message Context Property 608 specified in this document, exclusive of appendices. Each 609 interface SHOULD be implemented even when this will always result 610 in no operation, e.g. there is no action when the API specifies a 611 Property that is not available in a transport protocol implemented 612 on a specific platform. 614 o Implementations may use other representations for Transport 615 Property Names, e.g., by providing constants, but should provide a 616 straight-forward mapping between their representation and the 617 property names specified here. 619 5. Pre-Establishment Phase 621 The Pre-Establishment phase allows applications to specify properties 622 for the Connections they are about to make, or to query the API about 623 potential Connections they could make. 625 A Preconnection Object represents a potential Connection. It has 626 state that describes properties of a Connection that might exist in 627 the future. This state comprises Local Endpoint and Remote Endpoint 628 Objects that denote the endpoints of the potential Connection (see 629 Section 5.1), the Selection Properties (see Section 5.2), any 630 preconfigured Connection Properties (Section 11.1), and the security 631 parameters (see Section 5.3): 633 Preconnection := NewPreconnection(LocalEndpoint, 634 RemoteEndpoint, 635 TransportProperties, 636 SecurityParams) 638 The Local Endpoint MUST be specified if the Preconnection is used to 639 Listen() for incoming Connections, but is OPTIONAL if it is used to 640 Initiate() connections. The Remote Endpoint MUST be specified if the 641 Preconnection is used to Initiate() Connections, but is OPTIONAL if 642 it is used to Listen() for incoming Connections. The Local Endpoint 643 and the Remote Endpoint MUST both be specified if a peer-to-peer 644 Rendezvous is to occur based on the Preconnection. 646 Message Framers (see Section 10), if required, should be added to the 647 Preconnection during pre-establishment. 649 5.1. Specifying Endpoints 651 The transport services API uses the Local Endpoint and Remote 652 Endpoint types to refer to the endpoints of a transport connection. 653 Subtypes of these represent various different types of endpoint 654 identifiers, such as IP addresses, DNS names, and interface names, as 655 well as port numbers and service names. 657 RemoteSpecifier := NewRemoteEndpoint() 658 RemoteSpecifier.WithHostname("example.com") 659 RemoteSpecifier.WithService("https") 661 RemoteSpecifier := NewRemoteEndpoint() 662 RemoteSpecifier.WithIPv6Address(2001:db8:4920:e29d:a420:7461:7073:0a) 663 RemoteSpecifier.WithPort(443) 665 RemoteSpecifier := NewRemoteEndpoint() 666 RemoteSpecifier.WithIPv4Address(192.0.2.21) 667 RemoteSpecifier.WithPort(443) 669 LocalSpecifier := NewLocalEndpoint() 670 LocalSpecifier.WithInterface("en0") 671 LocalSpecifier.WithPort(443) 673 LocalSpecifier := NewLocalEndpoint() 674 LocalSpecifier.WithStunServer(address, port, credentials) 676 Implementations may also support additional endpoint representations 677 and provide a single NewEndpoint() call that takes different endpoint 678 representations. 680 Multiple endpoint identifiers can be specified for each Local 681 Endpoint and Remote Endpoint. For example, a Local Endpoint could be 682 configured with two interface names, or a Remote Endpoint could be 683 specified via both IPv4 and IPv6 addresses. These multiple 684 identifiers refer to the same transport endpoint. 686 The transport services API resolves names internally, when the 687 Initiate(), Listen(), or Rendezvous() method is called establish a 688 Connection. The API explicitly does not require the application to 689 resolve names, though there is a tradeoff between early and late 690 binding of addresses to names. Early binding allows the API 691 implementation to reduce connection setup latency, at the cost of 692 potentially limited scope for alternate path discovery during 693 Connection establishment, as well as potential additional information 694 leakage about application interest when used with a resolution method 695 (such as DNS without TLS) which does not protect query 696 confidentiality. 698 The Resolve() action on Preconnection can be used by the application 699 to force early binding when required, for example with some Network 700 Address Translator (NAT) traversal protocols (see Section 6.3). 702 5.2. Specifying Transport Properties 704 A Preconnection Object holds properties reflecting the application's 705 requirements and preferences for the transport. These include 706 Selection Properties for selecting protocol stacks and paths, as well 707 as Connection Properties for configuration of the detailed operation 708 of the selected Protocol Stacks. 710 The protocol(s) and path(s) selected as candidates during 711 establishment are determined and configured using these properties. 712 Since there could be paths over which some transport protocols are 713 unable to operate, or remote endpoints that support only specific 714 network addresses or transports, transport protocol selection is 715 necessarily tied to path selection. This may involve choosing 716 between multiple local interfaces that are connected to different 717 access networks. 719 Most Selection Properties are represented as preferences, which can 720 have one of five preference levels: 722 +------------+------------------------------------------------------+ 723 | Preference | Effect | 724 +------------+------------------------------------------------------+ 725 | Require | Select only protocols/paths providing the property, | 726 | | fail otherwise | 727 | | | 728 | Prefer | Prefer protocols/paths providing the property, | 729 | | proceed otherwise | 730 | | | 731 | Ignore | No preference | 732 | | | 733 | Avoid | Prefer protocols/paths not providing the property, | 734 | | proceed otherwise | 735 | | | 736 | Prohibit | Select only protocols/paths not providing the | 737 | | property, fail otherwise | 738 +------------+------------------------------------------------------+ 740 In addition, the pseudo-level "Default" can be used to reset the 741 property to the default level used by the implementation. This level 742 will never show up when queuing the value of a preference - the 743 effective preference must be returned instead. 745 Internally, the transport system will first exclude all protocols and 746 paths that match a Prohibit, then exclude all protocols and paths 747 that do not match a Require, then sort candidates according to 748 Preferred properties, and then use Avoided properties as a 749 tiebreaker. Selection Properties that select paths take preference 750 over those that select protocols. For example, if an application 751 indicates a preference for a specific path by specifying an 752 interface, but also a preference for a protocol not available on this 753 path, the transport system will try the path first, ignoring the 754 preference. 756 Selection, and Connection Properties, as well as defaults for Message 757 Properties, can be added to a Preconnection to configure the 758 selection process, and to further configure the eventually selected 759 protocol stack(s). They are collected into a TransportProperties 760 object to be passed into a Preconnection object: 762 TransportProperties := NewTransportProperties() 764 Individual properties are then added to the TransportProperties 765 Object: 767 TransportProperties.Add(property, value) 769 As preference typed selection properties may be used quite 770 frequently, implementations should provide additional convenience 771 functions as outlined in Appendix A.1. In addition, implementations 772 should provide a mechanism to create TransportProperties objects that 773 are preconfigured for common use cases as outlined in Appendix A.2. 775 For an existing Connection, the Transport Properties can be queried 776 any time by using the following call on the Connection Object: 778 TransportProperties := Connection.GetTransportProperties() 780 A Connection gets its Transport Properties either by being explicitly 781 configured via a Preconnection, by configuration after establishment, 782 or by inheriting them from an antecedent via cloning; see Section 6.4 783 for more. 785 Section 11.1 provides a list of Connection Properties, while 786 Selection Properties are listed in the subsections below. Note that 787 many properties are only considered during establishment, and can not 788 be changed after a Connection is established; however, they can be 789 queried. Querying a Selection Property after establishment yields 790 the value Required for properties of the selected protocol and path, 791 Avoid for properties avoided during selection, and Ignore for all 792 other properties. 794 An implementation of this interface must provide sensible defaults 795 for Selection Properties. The defaults given for each property below 796 represent a configuration that can be implemented over TCP. An 797 alternate set of default Protocol Selection Properties would 798 represent a configuration that can be implemented over UDP. 800 5.2.1. Reliable Data Transfer (Connection) 802 Name: reliability 804 This property specifies whether the application needs to use a 805 transport protocol that ensures that all data is received on the 806 other side without corruption. This also entails being notified when 807 a Connection is closed or aborted. The default is to Require 808 Reliable Data Transfer. 810 5.2.2. Preservation of Message Boundaries 812 Name: preserve-msg-boundaries 814 This property specifies whether the application needs or prefers to 815 use a transport protocol that preserves message boundaries. The 816 default is to Prefer Preservation of Message Boundaries. 818 5.2.3. Configure Per-Message Reliability 820 Name: per-msg-reliability 822 This property specifies whether an application considers it useful to 823 indicate its reliability requirements on a per-Message basis. This 824 property applies to Connections and Connection Groups. The default 825 is to Ignore this option. 827 5.2.4. Preservation of Data Ordering 829 Name: preserve-order 831 This property specifies whether the application wishes to use a 832 transport protocol that can ensure that data is received by the 833 application on the other end in the same order as it was sent. The 834 default is to Require Preservation of data ordering. 836 5.2.5. Use 0-RTT Session Establishment with an Idempotent Message 838 Name: zero-rtt-msg 840 This property specifies whether an application would like to supply a 841 Message to the transport protocol before Connection establishment, 842 which will then be reliably transferred to the other side before or 843 during Connection establishment, potentially multiple times (i.e., 844 multiple copies of the message data may be passed to the Remote 845 Endpoint). See also Section 7.4.4. The default is to Ignore this 846 option. Note that disabling this property has no effect for 847 protocols that are not connection-oriented and do not protect against 848 duplicated messages, e.g., UDP. 850 5.2.6. Multistream Connections in Group 852 Name: multistreaming 854 This property specifies that the application would prefer multiple 855 Connections within a Connection Group to be provided by streams of a 856 single underlying transport connection where possible. The default 857 is to Prefer this option. 859 5.2.7. Full Checksum Coverage on Sending 861 Name: per-msg-checksum-len-send 863 This property specifies whether the application desires protection 864 against corruption for all data transmitted on this Connection. 865 Disabling this property may enable to control checksum coverage later 866 (see Section 7.4.6). The default is to Require this option. 868 5.2.8. Full Checksum Coverage on Receiving 870 Name: per-msg-checksum-len-recv 872 This property specifies whether the application desires protection 873 against corruption for all data received on this Connection. The 874 default is to Require this option. 876 5.2.9. Congestion control 878 Name: congestion-control 880 This property specifies whether the application would like the 881 Connection to be congestion controlled or not. Note that if a 882 Connection is not congestion controlled, an application using such a 883 Connection should itself perform congestion control in accordance 884 with [RFC2914]. Also note that reliability is usually combined with 885 congestion control in protocol implementations, rendering "reliable 886 but not congestion controlled" a request that is unlikely to succeed. 887 The recommended default is to Require that the Connection is 888 congestion controlled. 890 5.2.10. Interface Instance or Type 892 Name: interface 894 Type: Set (Preference, Enumeration) 896 This property allows the application to select which specific network 897 interfaces or categories of interfaces it wants to "Require", 898 "Prohibit", "Prefer", or "Avoid". Note that marking a specific 899 interface as "Required" strictly limits path selection to a single 900 interface, and may often lead to less flexible and resilient 901 connection establishment. 903 In contrast to other Selection Properties, this property is a tuple 904 of an (Enumerated) interface identifier and a preference, and can 905 either be implemented directly as such, or for making one preference 906 available for each interface and interface type available on the 907 system. 909 The set of valid interface types is implementation- and system- 910 specific. For example, on a mobile device, there may be "Wi-Fi" and 911 "Cellular" interface types available; whereas on a desktop computer, 912 there may be "Wi-Fi" and "Wired Ethernet" interface types available. 913 An implementation should provide all types that are supported on the 914 local system to all remote systems, to allow applications to be 915 written generically. For example, if a single implementation is used 916 on both mobile devices and desktop devices, it should define the 917 "Cellular" interface type for both systems, since an application may 918 want to always "Prohibit Cellular". Note that marking a specific 919 interface type as "Required" limits path selection to a small set of 920 interfaces, and leads to less flexible and resilient connection 921 establishment. 923 The set of interface types is expected to change over time as new 924 access technologies become available. 926 Interface types should not be treated as a proxy for properties of 927 interfaces such as metered or unmetered network access. If an 928 application needs to prohibit metered interfaces, this should be 929 specified via Provisioning Domain attributes (see Section 5.2.11) or 930 another specific property. 932 5.2.11. Provisioning Domain Instance or Type 934 Name: pvd 936 Type: Set (Preference, Enumeration) 938 Similar to interface instances and types (see Section 5.2.10), this 939 property allows the application to control path selection by 940 selecting which specific Provisioning Domains or categories of 941 Provisioning Domains it wants to "Require", "Prohibit", "Prefer", or 942 "Avoid". Provisioning Domains define consistent sets of network 943 properties that may be more specific than network interfaces 944 [RFC7556]. 946 As with interface instances and types, this property is a tuple of an 947 (Enumerated) PvD identifier and a preference, and can either be 948 implemented directly as such, or for making one preference available 949 for each interface and interface type available on the system. 951 The identification of a specific Provisioning Domain (PvD) is defined 952 to be implementation- and system-specific, since there is not a 953 portable standard format for a PvD identitfier. For example, this 954 identifier may be a string name or an integer. As with requiring 955 specific interfaces, requiring a specific PvD strictly limits path 956 selection. 958 Categories or types of PvDs are also defined to be implementation- 959 and system-specific. These may be useful to identify a service that 960 is provided by a PvD. For example, if an application wants to use a 961 PvD that provides a Voice-Over-IP service on a Cellular network, it 962 can use the relevant PvD type to require some PvD that provides this 963 service, without needing to look up a particular instance. While 964 this does restrict path selection, it is broader than requiring 965 specific PvD instances or interface instances, and should be 966 preferred over these options. 968 5.2.12. Parallel Use of Multiple Paths 970 Name: multipath 972 This property specifies whether an application considers it useful to 973 transfer data across multiple paths between the same end hosts. 974 Generally, in most cases, this will improve performance (e.g., 975 achieve greater throughput). One possible side-effect is increased 976 jitter, which may be problematic for delay-sensitive applications. 977 The recommended default is to Ignore this option. 979 5.2.13. Direction of communication 981 Name: direction 983 Type: Enumeration 985 This property specifies whether an application wants to use the 986 connection for sending and/or receiving data. Possible values are: 988 Bidirectional: The connection must support sending and receiving 989 data 991 Unidirectional send: The connection must support sending data, and 992 the application cannot use the connection to receive any data 994 Unidirectional receive: The connection must support receiving data, 995 and the application cannot use the connection to send any data 997 The default is bidirectional. Since unidirectional communication can 998 be supported by transports offering bidirectional communication, 999 specifying unidirectional communication may cause a transport stack 1000 that supports bidirectional communication to be selected. 1002 5.2.14. Notification of excessive retransmissions 1004 Name: :retransmit-notify 1006 This property specifies whether an application considers it useful to 1007 be informed in case sent data was retransmitted more often than a 1008 certain threshold. The default is to Ignore this option. 1010 5.2.15. Notification of ICMP soft error message arrival 1012 Name: :soft-error-notify 1014 This property specifies whether an application considers it useful to 1015 be informed when an ICMP error message arrives that does not force 1016 termination of a connection. When set to true, received ICMP errors 1017 will be available as SoftErrors. Note that even if a protocol 1018 supporting this property is selected, not all ICMP errors will 1019 necessarily be delivered, so applications cannot rely on receiving 1020 them. The default is to Ignore this option. 1022 5.3. Specifying Security Parameters and Callbacks 1024 Most security parameters, e.g., TLS ciphersuites, local identity and 1025 private key, etc., may be configured statically. Others are 1026 dynamically configured during connection establishment. Thus, we 1027 partition security parameters and callbacks based on their place in 1028 the lifetime of connection establishment. Similar to Transport 1029 Properties, both parameters and callbacks are inherited during 1030 cloning (see Section 6.4). 1032 5.3.1. Pre-Connection Parameters 1034 Common parameters such as TLS ciphersuites are known to 1035 implementations. Clients should use common safe defaults for these 1036 values whenever possible. However, as discussed in 1037 [I-D.ietf-taps-transport-security], many transport security protocols 1038 require specific security parameters and constraints from the client 1039 at the time of configuration and actively during a handshake. These 1040 configuration parameters are created as follows: 1042 SecurityParameters := NewSecurityParameters() 1044 Security configuration parameters and sample usage follow: 1046 o Local identity and private keys: Used to perform private key 1047 operations and prove one's identity to the Remote Endpoint. 1048 (Note, if private keys are not available, e.g., since they are 1049 stored in hardware security modules (HSMs), handshake callbacks 1050 must be used. See below for details.) 1052 SecurityParameters.AddIdentity(identity) 1053 SecurityParameters.AddPrivateKey(privateKey, publicKey) 1055 o Supported algorithms: Used to restrict what parameters are used by 1056 underlying transport security protocols. When not specified, 1057 these algorithms should use known and safe defaults for the 1058 system. Parameters include: ciphersuites, supported groups, and 1059 signature algorithms. 1061 SecurityParameters.AddSupportedGroup(secp256k1) 1062 SecurityParameters.AddCiphersuite(TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256) 1063 SecurityParameters.AddSignatureAlgorithm(ed25519) 1065 o Session cache management: Used to tune cache capacity, lifetime, 1066 re-use, and eviction policies, e.g., LRU or FIFO. Constants and 1067 policies for these interfaces are implementation-specific. 1069 SecurityParameters.SetSessionCacheCapacity(MAX_CACHE_ELEMENTS) 1070 SecurityParameters.SetSessionCacheLifetime(SECONDS_PER_DAY) 1071 SecurityParameters.SetSessionCachePolicy(CachePolicyOneTimeUse) 1073 o Pre-Shared Key import: Used to install pre-shared keying material 1074 established out-of-band. Each pre-shared keying material is 1075 associated with some identity that typically identifies its use or 1076 has some protocol-specific meaning to the Remote Endpoint. 1078 SecurityParameters.AddPreSharedKey(key, identity) 1080 5.3.2. Connection Establishment Callbacks 1082 Security decisions, especially pertaining to trust, are not static. 1083 Once configured, parameters may also be supplied during connection 1084 establishment. These are best handled as client-provided callbacks. 1085 Security handshake callbacks that may be invoked during connection 1086 establishment include: 1088 o Trust verification callback: Invoked when a Remote Endpoint's 1089 trust must be validated before the handshake protocol can proceed. 1091 TrustCallback := NewCallback({ 1092 // Handle trust, return the result 1093 }) 1094 SecurityParameters.SetTrustVerificationCallback(trustCallback) 1096 o Identity challenge callback: Invoked when a private key operation 1097 is required, e.g., when local authentication is requested by a 1098 remote. 1100 ChallengeCallback := NewCallback({ 1101 // Handle challenge 1102 }) 1103 SecurityParameters.SetIdentityChallengeCallback(challengeCallback) 1105 6. Establishing Connections 1107 Before a Connection can be used for data transfer, it must be 1108 established. Establishment ends the pre-establishment phase; all 1109 transport properties and cryptographic parameter specification must 1110 be complete before establishment, as these will be used to select 1111 candidate Paths and Protocol Stacks for the Connection. 1112 Establishment may be active, using the Initiate() Action; passive, 1113 using the Listen() Action; or simultaneous for peer-to-peer, using 1114 the Rendezvous() Action. These Actions are described in the 1115 subsections below. 1117 6.1. Active Open: Initiate 1119 Active open is the Action of establishing a Connection to a Remote 1120 Endpoint presumed to be listening for incoming Connection requests. 1121 Active open is used by clients in client-server interactions. Active 1122 open is supported by this interface through the Initiate Action: 1124 Connection := Preconnection.Initiate(timeout?) 1126 The timeout parameter specifies how long to wait before aborting 1127 Active open. Before calling Initiate, the caller must have populated 1128 a Preconnection Object with a Remote Endpoint specifier, optionally a 1129 Local Endpoint specifier (if not specified, the system will attempt 1130 to determine a suitable Local Endpoint), as well as all properties 1131 necessary for candidate selection. 1133 The Initiate() Action consumes the Preconnection. Once Initiate() 1134 has been called, no further properties may be added to the 1135 Preconnection, and no subsequent establishment call may be made on 1136 the Preconnection. 1138 Once Initiate is called, the candidate Protocol Stack(s) may cause 1139 one or more candidate transport-layer connections to be created to 1140 the specified remote endpoint. The caller may immediately begin 1141 sending Messages on the Connection (see Section 7) after calling 1142 Initate(); note that any idempotent data sent while the Connection is 1143 being established may be sent multiple times or on multiple 1144 candidates. 1146 The following Events may be sent by the Connection after Initiate() 1147 is called: 1149 Connection -> Ready<> 1151 The Ready Event occurs after Initiate has established a transport- 1152 layer connection on at least one usable candidate Protocol Stack over 1153 at least one candidate Path. No Receive Events (see Section 8) will 1154 occur before the Ready Event for Connections established using 1155 Initiate. 1157 Connection -> InitiateError 1159 An InitiateError occurs either when the set of transport properties 1160 and security parameters cannot be fulfilled on a Connection for 1161 initiation (e.g. the set of available Paths and/or Protocol Stacks 1162 meeting the constraints is empty) or reconciled with the local and/or 1163 remote Endpoints; when the remote specifier cannot be resolved; or 1164 when no transport-layer connection can be established to the remote 1165 Endpoint (e.g. because the remote Endpoint is not accepting 1166 connections, the application is prohibited from opening a Connection 1167 by the operating system, or the establishment attempt has timed out 1168 for any other reason). 1170 See also Section 7.7 to combine Connection establishment and 1171 transmission of the first message in a single action. 1173 6.2. Passive Open: Listen 1175 Passive open is the Action of waiting for Connections from remote 1176 Endpoints, commonly used by servers in client-server interactions. 1177 Passive open is supported by this interface through the Listen Action 1178 and returns a Listener object: 1180 Listener := Preconnection.Listen() 1182 Before calling Listen, the caller must have initialized the 1183 Preconnection during the pre-establishment phase with a Local 1184 Endpoint specifier, as well as all properties necessary for Protocol 1185 Stack selection. A Remote Endpoint may optionally be specified, to 1186 constrain what Connections are accepted. The Listen() Action returns 1187 a Listener object. Once Listen() has been called, properties added 1188 to the Preconnection have no effect on the Listener and the 1189 Preconnection can be disposed of or reused. 1191 Listening continues until the global context shuts down, or until the 1192 Stop action is performed on the Listener object: 1194 Listener.Stop() 1196 After Stop() is called, the Listener can be disposed of. 1198 Listener -> ConnectionReceived 1200 The ConnectionReceived Event occurs when a Remote Endpoint has 1201 established a transport-layer connection to this Listener (for 1202 Connection-oriented transport protocols), or when the first Message 1203 has been received from the Remote Endpoint (for Connectionless 1204 protocols), causing a new Connection to be created. The resulting 1205 Connection is contained within the ConnectionReceived Event, and is 1206 ready to use as soon as it is passed to the application via the 1207 event. 1209 Listener.SetNewConnectionLimit(value) 1211 If the caller wants to rate-limit the number of inbound Connections 1212 that will be delivered, it can set a cap using 1213 SetNewConnectionLimit(). This mechanism allows a server to protect 1214 itself from being drained of resources. Each time a new Connection 1215 is delivered by the ConnectionReceived Event, the value is 1216 automatically decremented. Once the value reaches zero, no further 1217 Connections will be delivered until the caller sets the limit to a 1218 higher value. By default, this value is Infinite. The caller is 1219 also able to reset the value to Infinite at any point. 1221 Listener -> ListenError 1223 A ListenError occurs either when the Properties of the Preconnection 1224 cannot be fulfilled for listening, when the Local Endpoint (or Remote 1225 Endpoint, if specified) cannot be resolved, or when the application 1226 is prohibited from listening by policy. 1228 Listener -> Stopped<> 1230 A Stopped Event occurs after the Listener has stopped listening. 1232 6.3. Peer-to-Peer Establishment: Rendezvous 1234 Simultaneous peer-to-peer Connection establishment is supported by 1235 the Rendezvous() Action: 1237 Preconnection.Rendezvous() 1239 The Preconnection Object must be specified with both a Local Endpoint 1240 and a Remote Endpoint, and also the transport properties and security 1241 parameters needed for Protocol Stack selection. 1243 The Rendezvous() Action causes the Preconnection to listen on the 1244 Local Endpoint for an incoming Connection from the Remote Endpoint, 1245 while simultaneously trying to establish a Connection from the Local 1246 Endpoint to the Remote Endpoint. This corresponds to a TCP 1247 simultaneous open, for example. 1249 The Rendezvous() Action consumes the Preconnection. Once 1250 Rendezvous() has been called, no further properties may be added to 1251 the Preconnection, and no subsequent establishment call may be made 1252 on the Preconnection. 1254 Preconnection -> RendezvousDone 1256 The RendezvousDone<> Event occurs when a Connection is established 1257 with the Remote Endpoint. For Connection-oriented transports, this 1258 occurs when the transport-layer connection is established; for 1259 Connectionless transports, it occurs when the first Message is 1260 received from the Remote Endpoint. The resulting Connection is 1261 contained within the RendezvousDone<> Event, and is ready to use as 1262 soon as it is passed to the application via the Event. 1264 Preconnection -> RendezvousError 1266 An RendezvousError occurs either when the Preconnection cannot be 1267 fulfilled for listening, when the Local Endpoint or Remote Endpoint 1268 cannot be resolved, when no transport-layer connection can be 1269 established to the Remote Endpoint, or when the application is 1270 prohibited from rendezvous by policy. 1272 When using some NAT traversal protocols, e.g., Interactive 1273 Connectivity Establishment (ICE) [RFC5245], it is expected that the 1274 Local Endpoint will be configured with some method of discovering NAT 1275 bindings, e.g., a Session Traversal Utilities for NAT (STUN) server. 1276 In this case, the Local Endpoint may resolve to a mixture of local 1277 and server reflexive addresses. The Resolve() action on the 1278 Preconnection can be used to discover these bindings: 1280 []Preconnection := Preconnection.Resolve() 1282 The Resolve() call returns a list of Preconnection Objects, that 1283 represent the concrete addresses, local and server reflexive, on 1284 which a Rendezvous() for the Preconnection will listen for incoming 1285 Connections. These resolved Preconnections will share all other 1286 Properties with the Preconnection from which they are derived, though 1287 some Properties may be made more-specific by the resolution process. 1288 This list can be passed to a peer via a signalling protocol, such as 1289 SIP [RFC3261] or WebRTC [RFC7478], to configure the remote. 1291 6.4. Connection Groups 1293 Entangled Connections can be created using the Clone Action: 1295 Connection := Connection.Clone() 1297 Calling Clone on a Connection yields a group of two Connections: the 1298 parent Connection on which Clone was called, and the resulting cloned 1299 Connection. These connections are "entangled" with each other, and 1300 become part of a Connection Group. Calling Clone on any of these two 1301 Connections adds a third Connection to the Connection Group, and so 1302 on. Connections in a Connection Group share all Protocol Properties 1303 that are not applicable to a Message. 1305 In addition, incoming entangled Connections can be received by 1306 creating a Listener on an existing connection: 1308 Listener := Connection.Listen() 1310 Changing one of these Protocol Properties on one Connection in the 1311 group changes it for all others. Per-Message Protocol Properties, 1312 however, are not entangled. For example, changing "Timeout for 1313 aborting Connection" (see Section 11.1.4) on one Connection in a 1314 group will automatically change this Protocol Property for all 1315 Connections in the group in the same way. However, changing 1316 "Lifetime" (see Section 7.4.1) of a Message will only affect a single 1317 Message on a single Connection, entangled or not. 1319 If the underlying protocol supports multi-streaming, it is natural to 1320 use this functionality to implement Clone. In that case, entangled 1321 Connections are multiplexed together, giving them similar treatment 1322 not only inside endpoints but also across the end-to-end Internet 1323 path. 1325 If the underlying Protocol Stack does not support cloning, or cannot 1326 create a new stream on the given Connection, then attempts to clone a 1327 Connection will result in a CloneError: 1329 Connection -> CloneError 1331 The Protocol Property "Priority" operates on entangled Connections as 1332 in Section 7.4.2: when allocating available network capacity among 1333 Connections in a Connection Group, sends on Connections with higher 1334 Priority values will be prioritized over sends on Connections with 1335 lower Priority values. An ideal transport system implementation 1336 would assign each Connection the capacity share (M-N) x C / M, where 1337 N is the Connection's Priority value, M is the maximum Priority value 1338 used by all Connections in the group and C is the total available 1339 capacity. However, the Priority setting is purely advisory, and no 1340 guarantees are given about the way capacity is shared. Each 1341 implementation is free to implement a way to share capacity that it 1342 sees fit. 1344 7. Sending Data 1346 Once a Connection has been established, it can be used for sending 1347 data. Data is sent as Messages, which allow the application to 1348 communicate the boundaries of the data being transferred. By 1349 default, Send enqueues a complete Message, and takes optional per- 1350 Message properties (see Section 7.1). All Send actions are 1351 asynchronous, and deliver events (see Section 7.3). Sending partial 1352 Messages for streaming large data is also supported (see 1353 Section 7.5). 1355 Messages are sent on a Connection using the Send action: 1357 Connection.Send(messageData, messageContext?, endOfMessage?) 1359 where messageData is the data object to send. 1361 The optional messageContext parameter supports per-message properties 1362 and is described in Section 7.4. It can be used to identify send 1363 events (see Section 7.3) related to a specific message or to inspect 1364 meta-data related to the message sent (see Section 9). 1366 The optional endOfMessage parameter supports partial sending and is 1367 described in Section 7.5. 1369 7.1. Basic Sending 1371 The most basic form of sending on a connection involves enqueuing a 1372 single Data block as a complete Message, with default Message 1373 Properties. Message data is transferred as an array of bytes, and 1374 the resulting object contains both the byte array and the length of 1375 the array. 1377 messageData := "hello".bytes() 1378 Connection.Send(messageData) 1380 The interpretation of a Message to be sent is dependent on the 1381 implementation, and on the constraints on the Protocol Stacks implied 1382 by the Connection's transport properties. For example, a Message may 1383 be a single datagram for UDP Connections; or an HTTP Request for HTTP 1384 Connections. 1386 Some transport protocols can deliver arbitrarily sized Messages, but 1387 other protocols constrain the maximum Message size. Applications can 1388 query the Connection Property "Maximum Message size on send" 1389 (Section 11.1.8) to determine the maximum size allowed for a single 1390 Message. If a Message is too large to fit in the Maximum Message 1391 Size for the Connection, the Send will fail with a SendError event 1392 (Section 7.3.3). For example, it is invalid to send a Message over a 1393 UDP connection that is larger than the available datagram sending 1394 size. 1396 7.2. Sending Replies 1398 When a message is sent in response to a message received, the 1399 application may use the Message Context of the received Message to 1400 construct a Message Context for the reply. 1402 replyMessageContext := requestMessageContext.reply() 1404 By using the "replyMessageContext", the transport system is informed 1405 that the message to be sent is a response and can map the response to 1406 the same underlying transport connection or stream the request was 1407 received from. The concept of Message Contexts is described in 1408 Section 9. 1410 7.3. Send Events 1412 Like all Actions in this interface, the Send Action is asynchronous. 1413 There are several Events that can be delivered in response to Sending 1414 a Message. Exactly one Event (Sent, Expired, or SendError) will be 1415 delivered in reponse to each call to Send. These Events can be 1416 implemented as callbacks that allow the specific Event to be 1417 associated with the call to Send. 1419 Note that if partial Sends are used (Section 7.5), there will still 1420 be exactly one Send Event delivered for each call to Send. For 1421 example, if a Message expired while two requests to Send data for 1422 that Message are outstanding, there will be two Expired events 1423 delivered. 1425 7.3.1. Sent 1427 Connection -> Sent 1429 The Sent Event occurs when a previous Send Action has completed, 1430 i.e., when the data derived from the Message has been passed down or 1431 through the underlying Protocol Stack and is no longer the 1432 responsibility of this interface. The exact disposition of the 1433 Message (i.e., whether it has actually been transmitted, moved into a 1434 buffer on the network interface, moved into a kernel buffer, and so 1435 on) when the Sent Event occurs is implementation-specific. The Sent 1436 Event contains an implementation-specific reference to the Message to 1437 which it applies. 1439 Sent Events allow an application to obtain an understanding of the 1440 amount of buffering it creates. That is, if an application calls the 1441 Send Action multiple times without waiting for a Sent Event, it has 1442 created more buffer inside the transport system than an application 1443 that always waits for the Sent Event before calling the next Send 1444 Action. 1446 7.3.2. Expired 1448 Connection -> Expired 1450 The Expired Event occurs when a previous Send Action expired before 1451 completion; i.e. when the Message was not sent before its Lifetime 1452 (see Section 7.4.1) expired. This is separate from SendError, as it 1453 is an expected behavior for partially reliable transports. The 1454 Expired Event contains an implementation-specific reference to the 1455 Message to which it applies. 1457 7.3.3. SendError 1459 Connection -> SendError 1461 A SendError occurs when a Message could not be sent due to an error 1462 condition: an attempt to send a Message which is too large for the 1463 system and Protocol Stack to handle, some failure of the underlying 1464 Protocol Stack, or a set of Message Properties not consistent with 1465 the Connection's transport properties. The SendError contains an 1466 implementation-specific reference to the Message to which it applies. 1468 7.4. Message Properties 1470 Applications may need to annotate the Messages they send with extra 1471 information to control how data is scheduled and processed by the 1472 transport protocols in the Connection. Therefore a message context 1473 containing these properties can be passed to the Send Action. For 1474 other uses of the message context, see Section 9. 1476 Note that message properties are per-Message, not per-Send if partial 1477 Messages are sent (Section 7.5). All data blocks associated with a 1478 single Message share properties specified in the Message Contexts. 1479 For example, it would not make sense to have the beginning of a 1480 Message expire, but allow the end of a Message to still be sent. 1482 A MessageContext object contains metadata for Messages to be sent or 1483 received. 1485 messageData := "hello".bytes() 1486 messageContext := NewMessageContext() 1487 messageContext.add(parameter, value) 1488 Connection.Send(messageData, messageContext) 1490 The simpler form of Send, which does not take any messageContext, is 1491 equivalent to passing a default MessageContext without adding any 1492 Message Properties to it. 1494 If an application wants to override Message Properties for a specific 1495 message, it can acquire an empty MessageContext Object and add all 1496 desired Message Properties to that Object. It can then reuse the 1497 same messageContext Object for sending multiple Messages with the 1498 same properties. 1500 Properties may be added to a MessageContext object only before the 1501 context is used for sending. Once a messageContext has been used 1502 with a Send call, modifying any of its properties is invalid. 1504 Message Properties may be inconsistent with the properties of the 1505 Protocol Stacks underlying the Connection on which a given Message is 1506 sent. For example, a Connection must provide reliability to allow 1507 setting an infinitie value for the lifetime property of a Message. 1508 Sending a Message with Message Properties inconsistent with the 1509 Selection Properties of the Connection yields an error. 1511 The following Message Properties are supported: 1513 7.4.1. Lifetime 1515 Name: msg-lifetime 1517 Type: Integer 1519 Default: infinite 1521 Lifetime specifies how long a particular Message can wait to be sent 1522 to the remote endpoint before it is irrelevant and no longer needs to 1523 be (re-)transmitted. This is a hint to the transport system - it is 1524 not guaranteed that a Message will not be sent when its Lifetime has 1525 expired. 1527 Setting a Message's Lifetime to infinite indicates that the 1528 application does not wish to apply a time constraint on the 1529 transmission of the Message, but it does not express a need for 1530 reliable delivery; reliability is adjustable per Message via the 1531 "Reliable Data Transfer (Message)" property (see Section 7.4.7). The 1532 type and units of Lifetime are implementation-specific. 1534 7.4.2. Priority 1536 Name: msg-prio 1538 Type: Integer (non-negative) 1540 Default: 100 1542 This property represents a hierarchy of priorities. It can specify 1543 the priority of a Message, relative to other Messages sent over the 1544 same Connection. 1546 A Message with Priority 0 will yield to a Message with Priority 1, 1547 which will yield to a Message with Priority 2, and so on. Priorities 1548 may be used as a sender-side scheduling construct only, or be used to 1549 specify priorities on the wire for Protocol Stacks supporting 1550 prioritization. 1552 Note that this property is not a per-message override of the 1553 connection Priority - see Section 11.1.3. Both Priority properties 1554 may interact, but can be used independently and be realized by 1555 different mechanisms. 1557 7.4.3. Ordered 1559 Name: msg-ordered 1561 Type: Boolean 1563 Default: true 1565 If true, it specifies that the receiver-side transport protocol stack 1566 only deliver the Message to the receiving application after the 1567 previous ordered Message which was passed to the same Connection via 1568 the Send Action, when such a Message exists. If false, the Message 1569 may be delivered to the receiving application out of order. This 1570 property is used for protocols that support preservation of data 1571 ordering, see Section 5.2.4, but allow out-of-order delivery for 1572 certain messages. 1574 7.4.4. Idempotent 1576 Name: idempotent 1578 Type: Boolean 1580 Default: false 1582 If true, it specifies that a Message is safe to send to the remote 1583 endpoint more than once for a single Send Action. It is used to mark 1584 data safe for certain 0-RTT establishment techniques, where 1585 retransmission of the 0-RTT data may cause the remote application to 1586 receive the Message multiple times. 1588 Note that for protocols that do not protect against duplicated 1589 messages, e.g., UDP, all messages MUST be marked as Idempotent. In 1590 order to enable protocol selection to choose such a protocol, 1591 Idempotent MUST be added to the TransportProperties passed to the 1592 Preconnection. If such a protocol was chosen, disabling Idempotent 1593 on individual messages MUST result in a SendError. 1595 7.4.5. Final 1597 Type: Boolean 1599 Name: final 1600 Default: false 1602 If true, this Message is the last one that the application will send 1603 on a Connection. This allows underlying protocols to indicate to the 1604 Remote Endpoint that the Connection has been effectively closed in 1605 the sending direction. For example, TCP-based Connections can send a 1606 FIN once a Message marked as Final has been completely sent, 1607 indicated by marking endOfMessage. Protocols that do not support 1608 signalling the end of a Connection in a given direction will ignore 1609 this property. 1611 Note that a Final Message must always be sorted to the end of a list 1612 of Messages. The Final property overrides Priority and any other 1613 property that would re-order Messages. If another Message is sent 1614 after a Message marked as Final has already been sent on a 1615 Connection, the Send Action for the new Message will cause a 1616 SendError Event. 1618 7.4.6. Corruption Protection Length 1620 Name: msg-checksum-len 1622 Type: Integer (non-negative with -1 as special value) 1624 Default: full coverage 1626 This property specifies the minimum length of the section of the 1627 Message, starting from byte 0, that the application requires to be 1628 delivered without corruption due to lower layer errors. It is used 1629 to specify options for simple integrity protection via checksums. A 1630 value of 0 means that no checksum is required, and -1 means that the 1631 entire Message is protected by a checksum. Only full coverage is 1632 guaranteed, any other requests are advisory. 1634 7.4.7. Reliable Data Transfer (Message) 1636 Name: msg-reliable 1638 Type: Boolean 1640 Default: true 1642 When true, this property specifies that a message should be sent in 1643 such a way that the transport protocol ensures all data is received 1644 on the other side without corruption. Changing the 'Reliable Data 1645 Transfer' property on Messages is only possible for Connections that 1646 were established with the Selection Property 'Reliable Data Transfer 1647 (Connection)' enabled. When this is not the case, changing it will 1648 generate an error. Disabling this property indicates that the 1649 transport system may disable retransmissions or other reliability 1650 mechanisms for this particular Message, but such disabling is not 1651 guaranteed. 1653 7.4.8. Message Capacity Profile Override 1655 Name: msg-capacity-profile 1657 Type: Enumeration 1659 This enumerated property specifies the application's preferred 1660 tradeoffs for sending this Message; it is a per-Message override of 1661 the Capacity Profile protocol and path selection property (see 1662 Section 11.1.10). 1664 The following values are valid for Transmission Profile: 1666 Default: No special optimizations of the tradeoff between delay, 1667 delay variation, and bandwidth efficiency should be made when 1668 sending this message. 1670 Low Latency: Response time (latency) should be optimized at the 1671 expense of efficiently using the available capacity when sending 1672 this message. This can be used by the system to disable the 1673 coalescing of multiple small Messages into larger packets (Nagle's 1674 algorithm); to prefer immediate acknowledgment from the peer 1675 endpoint when supported by the underlying transport; to signal a 1676 preference for lower-latency, higher-loss treatment; and so on. 1678 [TODO: This is inconsistent with {prop-cap-profile}} - needs to be 1679 fixed] 1681 7.4.9. Singular Transmission 1683 Name: singular-transmission 1685 Type: Boolean 1687 Default: false 1689 This property specifies that a message should be sent and received as 1690 a single packet without transport-layer segmentation or network-layer 1691 fragmentation. Attempts to send a message with this property set 1692 with a size greater to the transport's current estimate of its 1693 maximum transmission segment size will result in a "SendError". When 1694 used with transports supporting this functionality and running over 1695 IP version 4, the Don't Fragment bit will be set. 1697 7.5. Partial Sends 1699 It is not always possible for an application to send all data 1700 associated with a Message in a single Send Action. The Message data 1701 may be too large for the application to hold in memory at one time, 1702 or the length of the Message may be unknown or unbounded. 1704 Partial Message sending is supported by passing an endOfMessage 1705 boolean parameter to the Send Action. This value is always true by 1706 default, and the simpler forms of Send are equivalent to passing true 1707 for endOfMessage. 1709 The following example sends a Message in two separate calls to Send. 1711 messageContext := NewMessageContext() 1712 messageContext.add(parameter, value) 1714 messageData := "hel".bytes() 1715 endOfMessage := false 1716 Connection.Send(messageData, messageContext, endOfMessage) 1718 messageData := "lo".bytes() 1719 endOfMessage := true 1720 Connection.Send(messageData, messageContext, endOfMessage) 1722 All data sent with the same MessageContext object will be treated as 1723 belonging to the same Message, and will constitute an in-order series 1724 until the endOfMessage is marked. Once the end of the Message is 1725 marked, the MessageContext object may be re-used as a new Message 1726 with identical parameters. 1728 7.6. Batching Sends 1730 To reduce the overhead of sending multiple small Messages on a 1731 Connection, the application may want to batch several Send actions 1732 together. This provides a hint to the system that the sending of 1733 these Messages should be coalesced when possible, and that sending 1734 any of the batched Messages may be delayed until the last Message in 1735 the batch is enqueued. 1737 Connection.Batch( 1738 Connection.Send(messageData) 1739 Connection.Send(messageData) 1740 ) 1742 7.7. Send on Active Open: InitiateWithSend 1744 For application-layer protocols where the Connection initiator also 1745 sends the first message, the InitiateWithSend() action combines 1746 Connection initiation with a first Message sent: 1748 Connection := Preconnection.InitiateWithSend(messageData, messageContext?, timeout?) 1750 Whenever possible, a messageContext should be provided to declare the 1751 message passed to InitiateWithSend as idempotent. This allows the 1752 transport system to make use of 0-RTT establishment in case this is 1753 supported by the available protocol stacks. When the selected 1754 stack(s) do not support transmitting data upon connection 1755 establishment, InitiateWithSend is identical to Initiate() followed 1756 by Send(). 1758 Neither partial sends nor send batching are supported by 1759 InitiateWithSend(). 1761 The Events that may be sent after InitiateWithSend() are equivalent 1762 to those that would be sent by an invocation of Initate() followed 1763 immediately by an invocation of Send(), with the caveat that a send 1764 failure that occurs because the Connection could not be established 1765 will not result in a SendError separate from the InitiateError 1766 signaling the failure of Connection establishment. 1768 8. Receiving Data 1770 Once a Connection is established, it can be used for receiving data. 1771 As with sending, data is received in terms of Messages. Receiving is 1772 an asynchronous operation, in which each call to Receive enqueues a 1773 request to receive new data from the connection. Once data has been 1774 received, or an error is encountered, an event will be delivered to 1775 complete the Receive request (see Section 8.2). 1777 As with sending, the type of the Message to be passed is dependent on 1778 the implementation, and on the constraints on the Protocol Stacks 1779 implied by the Connection's transport parameters. 1781 8.1. Enqueuing Receives 1783 Receive takes two parameters to specify the length of data that an 1784 application is willing to receive, both of which are optional and 1785 have default values if not specified. 1787 Connection.Receive(minIncompleteLength?, maxLength?) 1788 By default, Receive will try to deliver complete Messages in a single 1789 event (Section 8.2.1). 1791 The application can set a minIncompleteLength value to indicate the 1792 smallest partial Message data size in bytes that should be delivered 1793 in response to this Receive. By default, this value is infinite, 1794 which means that only complete Messages should be delivered (see 1795 Section 8.2.2 and Section 10 for more information on how this is 1796 accomplished). If this value is set to some smaller value, the 1797 associated receive event will be triggered only when at least that 1798 many bytes are available, or the Message is complete with fewer 1799 bytes, or the system needs to free up memory. Applications should 1800 always check the length of the data delivered to the receive event 1801 and not assume it will be as long as minIncompleteLength in the case 1802 of shorter complete Messages or memory issues. 1804 The maxLength argument indicates the maximum size of a Message in 1805 bytes the application is currently prepared to receive. The default 1806 value for maxLength is infinite. If an incoming Message is larger 1807 than the minimum of this size and the maximum Message size on receive 1808 for the Connection's Protocol Stack, it will be delivered via 1809 ReceivedPartial events (Section 8.2.2). 1811 Note that maxLength does not guarantee that the application will 1812 receive that many bytes if they are available; the interface may 1813 return ReceivedPartial events with less data than maxLength according 1814 to implementation constraints. 1816 8.2. Receive Events 1818 Each call to Receive will be paired with a single Receive Event, 1819 which can be a success or an error. This allows an application to 1820 provide backpressure to the transport stack when it is temporarily 1821 not ready to receive messages. 1823 8.2.1. Received 1825 Connection -> Received 1827 A Received event indicates the delivery of a complete Message. It 1828 contains two objects, the received bytes as messageData, and the 1829 metadata and properties of the received Message as messageContext. 1831 The messageData object provides access to the bytes that were 1832 received for this Message, along with the length of the byte array. 1833 The messageContext is provided to enable retrieving metadata about 1834 the message and referring to the message, e.g., to send replies and 1835 map responses to their requests. See Section 9 for details. 1837 See Section 10 for handling Message framing in situations where the 1838 Protocol Stack only provides a byte-stream transport. 1840 8.2.2. ReceivedPartial 1842 Connection -> ReceivedPartial 1844 If a complete Message cannot be delivered in one event, one part of 1845 the Message may be delivered with a ReceivedPartial event. In order 1846 to continue to receive more of the same Message, the application must 1847 invoke Receive again. 1849 Multiple invocations of ReceivedPartial deliver data for the same 1850 Message by passing the same MessageContext, until the endOfMessage 1851 flag is delivered or a ReceiveError occurs. All partial blocks of a 1852 single Message are delivered in order without gaps. This event does 1853 not support delivering discontiguous partial Messages. 1855 If the minIncompleteLength in the Receive request was set to be 1856 infinite (indicating a request to receive only complete Messages), 1857 the ReceivedPartial event may still be delivered if one of the 1858 following conditions is true: 1860 o the underlying Protocol Stack supports message boundary 1861 preservation, and the size of the Message is larger than the 1862 buffers available for a single message; 1864 o the underlying Protocol Stack does not support message boundary 1865 preservation, and the Message Framer (see Section 10) cannot 1866 determine the end of the message using the buffer space it has 1867 available; or 1869 o the underlying Protocol Stack does not support message boundary 1870 preservation, and no Message Framer was supplied by the 1871 application 1873 Note that in the absence of message boundary preservation or a 1874 Message Framer, all bytes received on the Connection will be 1875 represented as one large Message of indeterminate length. 1877 8.2.3. ReceiveError 1879 Connection -> ReceiveError 1881 A ReceiveError occurs when data is received by the underlying 1882 Protocol Stack that cannot be fully retrieved or parsed, or when some 1883 other indication is received that reception has failed. Such 1884 conditions that irrevocably lead to the termination of the Connection 1885 are signaled using ConnectionError instead (see Section 12). 1887 The ReceiveError event passes an optional associated MessageContext. 1888 This may indicate that a Message that was being partially received 1889 previously, but had not completed, encountered an error and will not 1890 be completed. 1892 8.3. Receive Message Properties 1894 Each Message Context may contain metadata from protocols in the 1895 Protocol Stack; which metadata is available is Protocol Stack 1896 dependent. These are exposed though additional read-only Message 1897 Properties that can be queried from the MessageContext object (see 1898 Section 9) passed by the receive event. The following metadata 1899 values are supported: 1901 8.3.1. ECN 1903 When available, Message metadata carries the value of the Explicit 1904 Congestion Notification (ECN) field. This information can be used 1905 for logging and debugging purposes, and for building applications 1906 which need access to information about the transport internals for 1907 their own operation. 1909 8.3.2. Early Data 1911 In some cases it may be valuable to know whether data was read as 1912 part of early data transfer (before connection establishment has 1913 finished). This is useful if applications need to treat early data 1914 separately, e.g., if early data has different security properties 1915 than data sent after connection establishment. In the case of TLS 1916 1.3, client early data can be replayed maliciously (see [RFC8446]). 1917 Thus, receivers may wish to perform additional checks for early data 1918 to ensure it is idempotent or not replayed. If TLS 1.3 is available 1919 and the recipient Message was sent as part of early data, the 1920 corresponding metadata carries a flag indicating as such. If early 1921 data is enabled, applications should check this metadata field for 1922 Messages received during connection establishment and respond 1923 accordingly. 1925 8.3.3. Receiving Final Messages 1927 The Message Context can indicate whether or not this Message is the 1928 Final Message on a Connection. For any Message that is marked as 1929 Final, the application can assume that there will be no more Messages 1930 received on the Connection once the Message has been completely 1931 delivered. This corresponds to the Final property that may be marked 1932 on a sent Message Section 7.4.5. 1934 Some transport protocols and peers may not support signaling of the 1935 Final property. Applications therefore should not rely on receiving 1936 a Message marked Final to know that the other endpoint is done 1937 sending on a connection. 1939 Any calls to Receive once the Final Message has been delivered will 1940 result in errors. 1942 9. Message Contexts 1944 Using the MessageContext object, the application can set and retrieve 1945 meta-data of the message, including Message Properties (see 1946 Section 7.4) and framing meta-data (see Section 10.2). Therefore, a 1947 MessageContext object can be passed to the Send action and is retuned 1948 by each Send and Receive related events. 1950 Message properties can be set and queried using the Message Context: 1952 MessageContext.add(scope?, parameter, value) 1953 PropertyValue := MessageContext.get(scope?, property) 1955 To get or set Message Properties, the optional scope parameter is 1956 left empty, for framing meta-data, the framer is passed. 1958 For MessageContexts returned by send events (see Section 7.3) and 1959 receive events (see Section 8.2), the application can query 1960 information about the local and remote endpoint: 1962 RemoteEndpoint := MessageContext.GetRemoteEndpoint() 1963 LocalEndpoint := MessageContext.GetLocalEndpoint() 1965 Message Contexts can also be used to send messages that are flagged 1966 as a reply to other messages, see Section 7.2 for details. If the 1967 message received was send by the remote endpoint as a reply to an 1968 earlier message and the transports provides this information, the 1969 MessageContext of the original request can be accessed using the 1970 Message Context of the reply: 1972 RequestMessageContext := MessageContext.GetOriginalRequest() 1974 10. Message Framers 1976 Although most applications communicate over a network using well- 1977 formed Messages, the boundaries and metadata of the Messages are 1978 often not directly communicated by the transport protocol itself. 1980 For example, HTTP applications send and receive HTTP messages over a 1981 byte-stream transport, requiring that the boundaries of HTTP messages 1982 be parsed out from the stream of bytes. 1984 Message Framers allow extending a Connection's Protocol Stack to 1985 define how to encapsulate or encode outbound Messages, and how to 1986 decapsulate or decode inbound data into Messages. Message Framers 1987 allow message boundaries to be preserved when using a Connection 1988 object, even when using byte-stream transports. This facility is 1989 designed based on the fact that many of the current application 1990 protocols evolved over TCP, which does not provide message boundary 1991 preservation, and since many of these protocols require message 1992 boundaries to function, each application layer protocol has defined 1993 its own framing. 1995 Note that while Message Framers add the most value when placed above 1996 a protocol that otherwise does not preserve message boundaries, they 1997 can also be used with datagram- or message-based protocols. In these 1998 cases, they add an additional transformation to further encode or 1999 encapsulate, and can potentially support packing multiple 2000 application-layer Messages into individual transport datagrams. 2002 The API to implement a Message Framer can vary depending on the 2003 implementation; guidance on implementing Message Framers can be found 2004 in [I-D.ietf-taps-impl]. 2006 10.1. Adding Message Framers to Connections 2008 The Message Framer object can be added to one or more Preconnections 2009 to run on top of transport protocols. Multiple Framers may be added. 2010 If multiple Framers are added, the last one added runs first when 2011 framing outbound messages, and last when parsing inbound data. 2013 The following example adds a basic HTTP Message Framer to a 2014 Preconnection: 2016 framer := NewHTTPMessageFramer() 2017 Preconnection.AddFramer(framer) 2019 10.2. Framing Meta-Data 2021 When sending Messages, applications can add specific Message values 2022 to a MessageContext (Section 9) that is intended for a Framer. This 2023 can be used, for example, to set the type of a Message for a TLV 2024 format. The namespace of values is custom for each unique Message 2025 Framer. 2027 messageContext := NewMessageContext() 2028 messageContext.add(framer, key, value) 2029 Connection.Send(messageData, messageContext) 2031 When an application receives a MessageContext in a Receive event, it 2032 can also look to see if a value was set by a specific Message Framer. 2034 messageContext.get(framer, key) -> value 2036 For example, if an HTTP Message Framer is used, the values could 2037 correspond to HTTP headers: 2039 httpFramer := NewHTTPMessageFramer() 2040 ... 2041 messageContext := NewMessageContext() 2042 messageContext.add(httpFramer, "accept", "text/html") 2044 11. Managing Connections 2046 During pre-establishment and after establishment, connections can be 2047 configured and queried using Connection Properties, and asynchronous 2048 information may be available about the state of the connection via 2049 Soft Errors. 2051 Connection Properties represent the configuration and state of the 2052 selected Protocol Stack(s) backing a Connection. These Connection 2053 Properties may be Generic, applying regardless of transport protocol, 2054 or Specific, applicable to a single implementation of a single 2055 transport protocol stack. Generic Connection Properties are defined 2056 in Section 11.1 below. Specific Protocol Properties are defined in a 2057 transport- and implementation-specific way, and must not be assumed 2058 to apply across different protocols. Attempts to set Specific 2059 Protocol Properties on a protocol stack not containing that specific 2060 protocol are simply ignored, and do not raise an error; however, too 2061 much reliance by an application on Specific Protocol Properties may 2062 significantly reduce the flexibility of a transport services 2063 implementation. 2065 The application can set and query Connection Properties on a per- 2066 Connection basis. Connection Properties that are not read-only can 2067 be set during pre-establishment (see Section 5.2), as well as on 2068 connections directly using the SetProperty action: 2070 Connection.SetProperty(property, value) 2072 At any point, the application can query Connection Properties. 2074 ConnectionProperties := Connection.GetProperties() 2075 Depending on the status of the connection, the queried Connection 2076 Properties will include different information: 2078 o The connection state, which can be one of the following: 2079 Establishing, Established, Closing, or Closed. 2081 o Whether the connection can be used to send data. A connection can 2082 not be used for sending if the connection was created with the 2083 Selection Property "Direction of Communication" set to 2084 "unidirectional receive" or if a Message marked as "Final" was 2085 sent over this connection, see Section 7.4.5. 2087 o Whether the connection can be used to receive data. A connection 2088 can not be used for reading if the connection was created with the 2089 Selection Property "Direction of Communication" set to 2090 "unidirectional send" or if a Message marked as "Final" was 2091 received, see Section 8.3.3. The latter is only supported by 2092 certain transport protocols, e.g., by TCP as half-closed 2093 connection. 2095 o For Connections that are Establishing: Transport Properties that 2096 the application specified on the Preconnection, see Section 5.2. 2098 o For Connections that are Established, Closing, or Closed: 2099 Selection (Section 5.2) and Connection Properties (Section 11.1) 2100 of the actual protocols that were selected and instantiated. 2101 Selection Properties indicate whether or not the Connection has or 2102 offers a certain Selection Property. Note that the actually 2103 instantiated protocol stack may not match all Protocol Selection 2104 Properties that the application specified on the Preconnection. 2105 For example, a certain Protocol Selection Property that an 2106 application specified as Preferred may not actually be present in 2107 the chosen protocol stack because none of the currently available 2108 transport protocols had this feature. 2110 o For Connections that are Established, additional properties of the 2111 path(s) in use. These properties can be derived from the local 2112 provisioning domain [RFC7556], measurements by the Protocol Stack, 2113 or other sources. 2115 11.1. Generic Connection Properties 2117 The Connection Properties defined as independent, and available on 2118 all Connections are defined in the subsections below. 2120 Note that many protocol properties have a corresponding selection 2121 property, which prefers protocols providing a specific transport 2122 feature that controlled by that protocol property. [EDITOR'S NOTE: 2123 todo: add these cross-references up to Section 5.2] 2125 11.1.1. Retransmission Threshold Before Excessive Retransmission 2126 Notification 2128 Name: retransmit-notify-threshold 2130 Type: Integer 2132 Default: -1 2134 This property specifies after how many retransmissions to inform the 2135 application about "Excessive Retransmissions". The special value -1 2136 means that this notification is disabled. 2138 11.1.2. Required Minimum Corruption Protection Coverage for Receiving 2140 Name: recv-checksum-len 2142 Type: Integer 2144 Default: -1 2146 This property specifies the part of the received data that needs to 2147 be covered by a checksum. It is given in Bytes. A value of 0 means 2148 that no checksum is required, and the special value -1 indicates full 2149 checksum coverage. 2151 11.1.3. Priority (Connection) 2153 Name: conn-prio 2155 Type: Integer 2157 Default: 100 2159 This Property is a non-negative integer representing the relative 2160 inverse priority of this Connection relative to other Connections in 2161 the same Connection Group. It has no effect on Connections not part 2162 of a Connection Group. As noted in Section 6.4, this property is not 2163 entangled when Connections are cloned. 2165 11.1.4. Timeout for Aborting Connection 2167 Name: conn-timeout 2169 Type: Numeric 2170 Default: -1 2172 This property specifies how long to wait before deciding that a 2173 Connection has failed when trying to reliably deliver data to the 2174 destination. Adjusting this Property will only take effect when the 2175 underlying stack supports reliability. The special value -1 means 2176 that this timeout is not scheduled to happen. 2178 11.1.5. Connection Group Transmission Scheduler 2180 Name: conn-scheduler 2182 Type: Enumeration 2184 Default: Weighted Fair Queueing (see Section 3.6 in [RFC8260]) 2186 This property specifies which scheduler should be used among 2187 Connections within a Connection Group, see Section 6.4. The set of 2188 schedulers can be taken from [RFC8260]. 2190 11.1.6. Maximum Message Size Concurrent with Connection Establishment 2192 Name: zero-rtt-msg-max-len 2194 Type: Integer (read only) 2196 This property represents the maximum Message size that can be sent 2197 before or during Connection establishment, see also Section 7.4.4. 2198 It is given in Bytes. 2200 11.1.7. Maximum Message Size Before Fragmentation or Segmentation 2202 Name: singular-transmission-msg-max-len 2204 Type: Integer (read only) 2206 This property, if applicable, represents the maximum Message size 2207 that can be sent without incurring network-layer fragmentation or 2208 transport layer segmentation at the sender. 2210 11.1.8. Maximum Message Size on Send 2212 Name: send-msg-max-len 2214 Type: Integer (read only) 2216 This property represents the maximum Message size that can be sent. 2218 11.1.9. Maximum Message Size on Receive 2220 Name: recv-msg-max-len 2222 Type: Integer (read only) 2224 This numeric property represents the maximum Message size that can be 2225 received. 2227 11.1.10. Capacity Profile 2229 Name: conn-capacity-profile 2231 This property specifies the desired network treatment for traffic 2232 sent by the application and the tradeoffs the application is prepared 2233 to make in path and protocol selection to receive that desired 2234 treatment. When the capacity profile is set to a value other than 2235 Default, the transport system should select paths and profiles to 2236 optimize for the capacity profile specified. The following values 2237 are valid for the Capacity Profile: 2239 Default: The application makes no representation about its expected 2240 capacity profile. No special optimizations of the tradeoff 2241 between delay, delay variation, and bandwidth efficiency should be 2242 made when selecting and configuring transport protocol stacks. 2243 Transport system implementations that map the requested capacity 2244 profile onto per-connection DSCP signaling without multiplexing 2245 SHOULD assign the DSCP Default Forwarding [RFC2474] PHB; when the 2246 Connection is multiplexed, the guidelines in Section 6 of 2247 [RFC7657] apply. 2249 Scavenger: The application is not interactive. It expects to send 2250 and/or receive data without any urgency. This can, for example, 2251 be used to select protocol stacks with scavenger transmission 2252 control and/or to assign the traffic to a lower-effort service. 2253 Transport system implementations that map the requested capacity 2254 profile onto per-connection DSCP signaling without multiplexing 2255 SHOULD assign the DSCP Less than Best Effort [LE-PHB] PHB; when 2256 the Connection is multiplexed, the guidelines in Section 6 of 2257 [RFC7657] apply. 2259 Low Latency/Interactive: The application is interactive, and prefers 2260 loss to latency. Response time should be optimized at the expense 2261 of bandwidth efficiency and delay variation when sending on this 2262 connection. This can be used by the system to disable the 2263 coalescing of multiple small Messages into larger packets (Nagle's 2264 algorithm); to prefer immediate acknowledgment from the peer 2265 endpoint when supported by the underlying transport; and so on. 2267 Transport system implementations that map the requested capacity 2268 profile onto per-connection DSCP signaling without multiplexing 2269 SHOULD assign the DSCP Expedited Forwarding [RFC3246] PHB; when 2270 the Connection is multiplexed, the guidelines in Section 6 of 2271 [RFC7657] apply. 2273 Low Latency/Non-Interactive: The application prefers loss to latency 2274 but is not interactive. Response time should be optimized at the 2275 expense of bandwidth efficiency and delay variation when sending 2276 on this connection.Transport system implementations that map the 2277 requested capacity profile onto per-connection DSCP signaling 2278 without multiplexing SHOULD assign a DSCP Assured Forwarding 2279 (AF21,AF22,AF23,AF24) [RFC2597] PHB; when the Connection is 2280 multiplexed, the guidelines in Section 6 of [RFC7657] apply. 2282 Constant-Rate Streaming: The application expects to send/receive 2283 data at a constant rate after Connection establishment. Delay and 2284 delay variation should be minimized at the expense of bandwidth 2285 efficiency. This implies that the Connection may fail if the 2286 desired rate cannot be maintained across the Path. A transport 2287 may interpret this capacity profile as preferring a circuit 2288 breaker [RFC8084] to a rate-adaptive congestion controller. 2289 Transport system implementations that map the requested capacity 2290 profile onto per-connection DSCP signaling without multiplexing 2291 SHOULD assign a DSCP Assured Forwarding (AF31,AF32,AF33,AF34) 2292 [RFC2597] PHB; when the Connection is multiplexed, the guidelines 2293 in Section 6 of [RFC7657] apply. 2295 High Throughput Data: The application expects to send/receive data 2296 at the maximum rate allowed by its congestion controller over a 2297 relatively long period of time. Transport system implementations 2298 that map the requested capacity profile onto per-connection DSCP 2299 signaling without multiplexing SHOULD assign a DSCP Assured 2300 Forwarding (AF11,AF12,AF13,AF14) [RFC2597] PHB per Section 4.8 of 2301 [RFC4594]. When the Connection is multiplexed, the guidelines in 2302 Section 6 of [RFC7657] apply. 2304 The Capacity Profile for a selected protocol stack may be modified on 2305 a per-Message basis using the Transmission Profile Message Property; 2306 see Section 7.4.8. 2308 11.1.11. Bounds on Send or Receive Rate 2310 Name: max-send-rate / max-recv-rate 2312 Type: Numeric / Numeric 2314 Default: -1 / -1 (unlimited, for both values) 2315 This property specifies an upper-bound rate that a transfer is not 2316 expected to exceed (even if flow control and congestion control allow 2317 higher rates), and/or a lower-bound rate below which the application 2318 does not deem a data transfer useful. It is given in bits per 2319 second. The special value -1 indicates that no bound is specified. 2321 11.1.12. TCP-specific Property: User Timeout 2323 This property specifies, for the case TCP becomes the chosen 2324 transport protocol: 2326 Advertised User Timeout (name: tcp.user-timeout-value, type: 2327 Integer): 2328 a time value (default: the TCP default) to be advertised via the 2329 User Timeout Option (UTO) for the TCP at the remote endpoint to 2330 adapt its own "Timeout for aborting Connection" (see 2331 Section 11.1.4) value accordingly. 2333 User Timeout Enabled (name: tcp.user-timeout, type: Boolean): a bool 2334 ean (default false) to control whether the UTO option is enabled 2335 for a connection. This applies to both sending and receiving. 2337 Changeable (name: tcp.user-timeout-recv, type: Boolean): a boolean 2338 (default true) which controls whether the "Timeout for aborting 2339 Connection" (see Section 11.1.4) may be changed based on a UTO 2340 option received from the remote peer. This boolean becomes false 2341 when "Timeout for aborting Connection" (see Section 11.1.4) is 2342 used. 2344 All of the above parameters are optional (e.g., it is possible to 2345 specify "User Timeout Enabled" as true, but not specify an Advertised 2346 User Timeout value; in this case, the TCP default will be used). 2348 11.2. Soft Errors 2350 Asynchronous introspection is also possible, via the SoftError Event. 2351 This event informs the application about the receipt of an ICMP error 2352 message related to the Connection. This will only happen if the 2353 underlying protocol stack supports access to soft errors; however, 2354 even if the underlying stack supports it, there is no guarantee that 2355 a soft error will be signaled. 2357 Connection -> SoftError<> 2359 11.3. Excessive retransmissions 2361 This event notifies the application of excessive retransmissions, 2362 based on a configured threshold (see Section 11.1.1). This will only 2363 happen if the underlying protocol stack supports reliability and, 2364 with it, such notifications. 2366 Connection -> ExcessiveRetransmission<> 2368 12. Connection Termination 2370 Close terminates a Connection after satisfying all the requirements 2371 that were specified regarding the delivery of Messages that the 2372 application has already given to the transport system. For example, 2373 if reliable delivery was requested for a Message handed over before 2374 calling Close, the transport system will ensure that this Message is 2375 indeed delivered. If the Remote Endpoint still has data to send, it 2376 cannot be received after this call. 2378 Connection.Close() 2380 The Closed Event can inform the application that the Remote Endpoint 2381 has closed the Connection; however, there is no guarantee that a 2382 remote Close will indeed be signaled. 2384 Connection -> Closed<> 2386 Abort terminates a Connection without delivering remaining data: 2388 Connection.Abort() 2390 A ConnectionError informs the application that data to could not be 2391 delivered after a timeout, or the other side has aborted the 2392 Connection; however, there is no guarantee that an Abort will indeed 2393 be signaled. 2395 Connection -> ConnectionError 2397 13. Connection State and Ordering of Operations and Events 2399 As this interface is designed to be independent of an 2400 implementation's concurrency model, the details of how exactly 2401 actions are handled, and on which threads/callbacks events are 2402 dispatched, are implementation dependent. 2404 Each transition of connection state is associated with one of more 2405 events: 2407 o Ready<> occurs when a Connection created with Initiate() or 2408 InitiateWithSend() transitions to Established state. 2410 o ConnectionReceived<> occurs when a Connection created with 2411 Listen() transitions to Established state. 2413 o RendezvousDone<> occurs when a Connection created with 2414 Rendezvous() transitions to Established state. 2416 o Closed<> occurs when a Connection transitions to Closed state 2417 without error. 2419 o InitiateError<> occurs when a Connection created with Initiate() 2420 transitions from Establishing state to Closed state due to an 2421 error. 2423 o ConnectionError<> occurs when a Connection transitions to Closed 2424 state due to an error in all other circumstances. 2426 The interface provides the following guarantees about the ordering of 2427 operations: 2429 o Sent<> events will occur on a Connection in the order in which the 2430 Messages were sent (i.e., delivered to the kernel or to the 2431 network interface, depending on implementation). 2433 o Received<> will never occur on a Connection before it is 2434 Established; i.e. before a Ready<> event on that Connection, or a 2435 ConnectionReceived<> or RendezvousDone<> containing that 2436 Connection. 2438 o No events will occur on a Connection after it is Closed; i.e., 2439 after a Closed<> event, an InitiateError<> or ConnectionError<> on 2440 that connection. To ensure this ordering, Closed<> will not occur 2441 on a Connection while other events on the Connection are still 2442 locally outstanding (i.e., known to the interface and waiting to 2443 be dealt with by the application). ConnectionError<> may occur 2444 after Closed<>, but the interface must gracefully handle all cases 2445 where application ignores these errors. 2447 14. IANA Considerations 2449 RFC-EDITOR: Please remove this section before publication. 2451 This document has no Actions for IANA. Later versions of this 2452 document may create IANA registries for generic transport property 2453 names and transport property namespaces (see Section 4.2.1). 2455 15. Security Considerations 2457 This document describes a generic API for interacting with a 2458 transport services (TAPS) system. Part of this API includes 2459 configuration details for transport security protocols, as discussed 2460 in Section 5.3. It does not recommend use (or disuse) of specific 2461 algorithms or protocols. Any API-compatible transport security 2462 protocol should work in a TAPS system. 2464 16. Acknowledgements 2466 This work has received funding from the European Union's Horizon 2020 2467 research and innovation programme under grant agreements No. 644334 2468 (NEAT) and No. 688421 (MAMI). 2470 This work has been supported by Leibniz Prize project funds of DFG - 2471 German Research Foundation: Gottfried Wilhelm Leibniz-Preis 2011 (FKZ 2472 FE 570/4-1). 2474 This work has been supported by the UK Engineering and Physical 2475 Sciences Research Council under grant EP/R04144X/1. 2477 This work has been supported by the Research Council of Norway under 2478 its "Toppforsk" programme through the "OCARINA" project. 2480 Thanks to Stuart Cheshire, Josh Graessley, David Schinazi, and Eric 2481 Kinnear for their implementation and design efforts, including Happy 2482 Eyeballs, that heavily influenced this work. Thanks to Laurent Chuat 2483 and Jason Lee for initial work on the Post Sockets interface, from 2484 which this work has evolved. 2486 17. References 2488 17.1. Normative References 2490 [I-D.ietf-taps-arch] 2491 Pauly, T., Trammell, B., Brunstrom, A., Fairhurst, G., 2492 Perkins, C., Tiesel, P., and C. Wood, "An Architecture for 2493 Transport Services", draft-ietf-taps-arch-04 (work in 2494 progress), July 2019. 2496 [I-D.ietf-tsvwg-rtcweb-qos] 2497 Jones, P., Dhesikan, S., Jennings, C., and D. Druta, "DSCP 2498 Packet Markings for WebRTC QoS", draft-ietf-tsvwg-rtcweb- 2499 qos-18 (work in progress), August 2016. 2501 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2502 Requirement Levels", BCP 14, RFC 2119, 2503 DOI 10.17487/RFC2119, March 1997, 2504 . 2506 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2507 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2508 May 2017, . 2510 [RFC8303] Welzl, M., Tuexen, M., and N. Khademi, "On the Usage of 2511 Transport Features Provided by IETF Transport Protocols", 2512 RFC 8303, DOI 10.17487/RFC8303, February 2018, 2513 . 2515 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2516 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2517 . 2519 17.2. Informative References 2521 [I-D.ietf-taps-impl] 2522 Brunstrom, A., Pauly, T., Enghardt, T., Grinnemo, K., 2523 Jones, T., Tiesel, P., Perkins, C., and M. Welzl, 2524 "Implementing Interfaces to Transport Services", draft- 2525 ietf-taps-impl-04 (work in progress), July 2019. 2527 [I-D.ietf-taps-minset] 2528 Welzl, M. and S. Gjessing, "A Minimal Set of Transport 2529 Services for End Systems", draft-ietf-taps-minset-11 (work 2530 in progress), September 2018. 2532 [I-D.ietf-taps-transport-security] 2533 Wood, C., Enghardt, T., Pauly, T., Perkins, C., and K. 2534 Rose, "A Survey of Transport Security Protocols", draft- 2535 ietf-taps-transport-security-09 (work in progress), 2536 September 2019. 2538 [LE-PHB] Bless, R., "A Lower Effort Per-Hop Behavior (LE PHB) for 2539 Differentiated Services", draft-ietf-tsvwg-le-phb-10 (work 2540 in progress), March 2019. 2542 [PROTOCOL-WARS] 2543 Computer History Museum, ., "Protocol Wars (Revolution - 2544 The First 2000 Years of Computing)", 2019, 2545 . 2548 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 2549 RFC 793, DOI 10.17487/RFC0793, September 1981, 2550 . 2552 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 2553 "Definition of the Differentiated Services Field (DS 2554 Field) in the IPv4 and IPv6 Headers", RFC 2474, 2555 DOI 10.17487/RFC2474, December 1998, 2556 . 2558 [RFC2597] Heinanen, J., Baker, F., Weiss, W., and J. Wroclawski, 2559 "Assured Forwarding PHB Group", RFC 2597, 2560 DOI 10.17487/RFC2597, June 1999, 2561 . 2563 [RFC2914] Floyd, S., "Congestion Control Principles", BCP 41, 2564 RFC 2914, DOI 10.17487/RFC2914, September 2000, 2565 . 2567 [RFC3246] Davie, B., Charny, A., Bennet, J., Benson, K., Le Boudec, 2568 J., Courtney, W., Davari, S., Firoiu, V., and D. 2569 Stiliadis, "An Expedited Forwarding PHB (Per-Hop 2570 Behavior)", RFC 3246, DOI 10.17487/RFC3246, March 2002, 2571 . 2573 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 2574 A., Peterson, J., Sparks, R., Handley, M., and E. 2575 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 2576 DOI 10.17487/RFC3261, June 2002, 2577 . 2579 [RFC4594] Babiarz, J., Chan, K., and F. Baker, "Configuration 2580 Guidelines for DiffServ Service Classes", RFC 4594, 2581 DOI 10.17487/RFC4594, August 2006, 2582 . 2584 [RFC5245] Rosenberg, J., "Interactive Connectivity Establishment 2585 (ICE): A Protocol for Network Address Translator (NAT) 2586 Traversal for Offer/Answer Protocols", RFC 5245, 2587 DOI 10.17487/RFC5245, April 2010, 2588 . 2590 [RFC7478] Holmberg, C., Hakansson, S., and G. Eriksson, "Web Real- 2591 Time Communication Use Cases and Requirements", RFC 7478, 2592 DOI 10.17487/RFC7478, March 2015, 2593 . 2595 [RFC7556] Anipko, D., Ed., "Multiple Provisioning Domain 2596 Architecture", RFC 7556, DOI 10.17487/RFC7556, June 2015, 2597 . 2599 [RFC7657] Black, D., Ed. and P. Jones, "Differentiated Services 2600 (Diffserv) and Real-Time Communication", RFC 7657, 2601 DOI 10.17487/RFC7657, November 2015, 2602 . 2604 [RFC8084] Fairhurst, G., "Network Transport Circuit Breakers", 2605 BCP 208, RFC 8084, DOI 10.17487/RFC8084, March 2017, 2606 . 2608 [RFC8095] Fairhurst, G., Ed., Trammell, B., Ed., and M. Kuehlewind, 2609 Ed., "Services Provided by IETF Transport Protocols and 2610 Congestion Control Mechanisms", RFC 8095, 2611 DOI 10.17487/RFC8095, March 2017, 2612 . 2614 [RFC8260] Stewart, R., Tuexen, M., Loreto, S., and R. Seggelmann, 2615 "Stream Schedulers and User Message Interleaving for the 2616 Stream Control Transmission Protocol", RFC 8260, 2617 DOI 10.17487/RFC8260, November 2017, 2618 . 2620 Appendix A. Convenience Functions 2622 A.1. Adding Preference Properties 2624 As Selection Properties of type Preference will be added to a 2625 TransportProperties object quite frequently, implementations should 2626 provide special actions for adding each preference level i.e, 2627 "TransportProperties.Add(some_property, avoid)" is equivalent to 2628 "TransportProperties.Avoid(some_property)": 2630 TransportProperties.Require(property) 2631 TransportProperties.Prefer(property) 2632 TransportProperties.Ignore(property) 2633 TransportProperties.Avoid(property) 2634 TransportProperties.Prohibit(property) 2635 TransportProperties.Default(property) 2637 A.2. Transport Property Profiles 2639 To ease the use of the interface specified by this document, 2640 implementations should provide a mechanism to create Transport 2641 Property objects (see Section 5.2) that are pre-configured with 2642 frequently used sets of properties. Implementations should at least 2643 short-hands to specify the following property profiles: 2645 A.2.1. reliable-inorder-stream 2647 This profile provides reliable, in-order transport service with 2648 congestion control. An example of a protocol that provides this 2649 service is TCP. It should consist of the following properties: 2651 +-------------------------+---------+ 2652 | Property | Value | 2653 +-------------------------+---------+ 2654 | reliability | require | 2655 | | | 2656 | preserve-order | require | 2657 | | | 2658 | congestion-control | require | 2659 | | | 2660 | preserve-msg-boundaries | ignore | 2661 +-------------------------+---------+ 2663 A.2.2. reliable-message 2665 This profile provides message-preserving, reliable, in-order 2666 transport service with congestion control. An example of a protocol 2667 that provides this service is SCTP. It should consist of the 2668 following properties: 2670 +-------------------------+---------+ 2671 | Property | Value | 2672 +-------------------------+---------+ 2673 | reliability | require | 2674 | | | 2675 | preserve-order | require | 2676 | | | 2677 | congestion-control | require | 2678 | | | 2679 | preserve-msg-boundaries | require | 2680 +-------------------------+---------+ 2682 A.2.3. unreliable-datagram 2684 This profile provides unreliable datagram transport service. An 2685 example of a protocol that provides this service is UDP. It should 2686 consist of the following properties: 2688 +-------------------------+---------+ 2689 | Property | Value | 2690 +-------------------------+---------+ 2691 | reliability | ignore | 2692 | | | 2693 | preserve-order | ignore | 2694 | | | 2695 | congestion-control | ignore | 2696 | | | 2697 | preserve-msg-boundaries | require | 2698 | | | 2699 | idempotent | true | 2700 +-------------------------+---------+ 2702 Applications that choose this Transport Property Profile for latency 2703 reasons should also consider setting the Capacity Profile Property, 2704 see Section 11.1.10 accordingly and my benefit from controlling 2705 checksum coverage, see Section 5.2.7 and Section 5.2.8. 2707 Appendix B. Additional Properties 2709 The interface specified by this document represents the minimal 2710 common interface to an endpoint in the transport services 2711 architecture [I-D.ietf-taps-arch], based upon that architecture and 2712 on the minimal set of transport service features elaborated in 2713 [I-D.ietf-taps-minset]. However, the interface has been designed 2714 with extension points to allow the implementation of features beyond 2715 those in the minimal common interface: Protocol Selection Properties, 2716 Path Selection Properties, and Message Properties are open sets. 2717 Implementations of the interface are free to extend these sets to 2718 provide additional expressiveness to applications written on top of 2719 them. 2721 This appendix enumerates a few additional properties that could be 2722 used to enhance transport protocol and/or path selection, or the 2723 transmission of messages given a Protocol Stack that implements them. 2724 These are not part of the interface, and may be removed from the 2725 final document, but are presented here to support discussion within 2726 the TAPS working group as to whether they should be added to a future 2727 revision of the base specification. 2729 B.1. Experimental Transport Properties 2731 The following Transport Properties might be made available in 2732 addition to those specified in Section 5.2, Section 11.1, and 2733 Section 7.4. 2735 B.1.1. Cost Preferences 2737 [EDITOR'S NOTE: At IETF 103, opinions were that this property should 2738 stay, but it was also said that this is maybe not "on the right 2739 level". If / when moving it to the main text, note that this is 2740 meant to be applicable to a Preconnection or a Message.] 2742 Name: cost-preferences 2744 Type: Enumeration 2746 This property describes what an application prefers regarding 2747 monetary costs, e.g., whether it considers it acceptable to utilize 2748 limited data volume. It provides hints to the transport system on 2749 how to handle trade-offs between cost and performance or reliability. 2751 Possible values are: 2753 No Expense: Avoid transports associated with monetary cost 2755 Optimize Cost: Prefer inexpensive transports and accept service 2756 degradation 2758 Balance Cost: Use system policy to balance cost and other criteria 2760 Ignore Cost: Ignore cost, choose transport solely based on other 2761 criteria 2763 The default is "Balance Cost". 2765 Appendix C. Sample API definition in Go 2767 This document defines an abstract interface. To illustrate how this 2768 would map concretely into a programming language, an API interface 2769 definition in Go is available online at https://github.com/mami- 2770 project/postsocket. Documentation for this API - an illustration of 2771 the documentation an application developer would see for an instance 2772 of this interface - is available online at 2773 https://godoc.org/github.com/mami-project/postsocket. This API 2774 definition will be kept largely in sync with the development of this 2775 abstract interface definition. 2777 Appendix D. Relationship to the Minimal Set of Transport Services for 2778 End Systems 2780 [I-D.ietf-taps-minset] identifies a minimal set of transport services 2781 that end systems should offer. These services make all non-security- 2782 related transport features of TCP, MPTCP, UDP, UDP-Lite, SCTP and 2783 LEDBAT available that 1) require interaction with the application, 2784 and 2) do not get in the way of a possible implementation over TCP 2785 (or, with limitations, UDP). The following text explains how this 2786 minimal set is reflected in the present API. For brevity, it is 2787 based on the list in Section 4.1 of [I-D.ietf-taps-minset], updated 2788 according to the discussion in Section 5 of [I-D.ietf-taps-minset]. 2789 This list is a subset of the transport features in Appendix A of 2790 [I-D.ietf-taps-minset], which refers to the primitives in "pass 2" 2791 (Section 4) of [RFC8303] for further details on the implementation 2792 with TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT. 2794 [EDITOR'S NOTE: This is early text. In the future, this section will 2795 contain backward references, which we currently avoid because things 2796 are still being moved around and names / categories etc. are 2797 changing.] 2799 o Connect: "Initiate" Action. 2801 o Listen: "Listen" Action. 2803 o Specify number of attempts and/or timeout for the first 2804 establishment message: "timeout" parameter of "Initiate" or 2805 "InitiateWithSend" Action. 2807 o Disable MPTCP: "Parallel Use of Multiple Paths" Property. 2809 o Hand over a message to reliably transfer (possibly multiple times) 2810 before connection establishment: "InitiateWithSend" Action. 2812 o Change timeout for aborting connection (using retransmit limit or 2813 time value): "Timeout for Aborting Connection" property, using a 2814 time value. 2816 o Timeout event when data could not be delivered for too long: 2817 "ConnectionError" Event. 2819 o Suggest timeout to the peer: "TCP-specific Property: User 2820 Timeout". 2822 o Notification of Excessive Retransmissions (early warning below 2823 abortion threshold): "Notification of excessive retransmissions" 2824 property. 2826 o Notification of ICMP error message arrival: "Notification of ICMP 2827 soft error message arrival" property. 2829 o Choose a scheduler to operate between streams of an association: 2830 "Connection Group Transmission Scheduler" property. 2832 o Configure priority or weight for a scheduler: "Priority 2833 (Connection)" property. 2835 o "Specify checksum coverage used by the sender" and "Disable 2836 checksum when sending": "Corruption Protection Length" property 2837 and "Full Checksum Coverage on Sending" property. 2839 o "Specify minimum checksum coverage required by receiver" and 2840 "Disable checksum requirement when receiving": "Required Minimum 2841 Corruption Protection Coverage for Receiving" property and "Full 2842 Checksum Coverage on Receiving" property. 2844 o "Specify DF" field and "Request not to bundle messages:" The 2845 "Singular Transmission" Message property combines both of these 2846 requests, i.e. if a request not to bundle messages is made, this 2847 also turns off DF in case of protocols that allow this (only UDP 2848 and UDP-Lite, which cannot bundle messages anyway). 2850 o Get max. transport-message size that may be sent using a non- 2851 fragmented IP packet from the configured interface: "Maximum 2852 Message Size Before Fragmentation or Segmentation" property. 2854 o Get max. transport-message size that may be received from the 2855 configured interface: "Maximum Message Size on Receive" property. 2857 o Obtain ECN field: "ECN" is a defined read-only Message Property of 2858 the MessageContext object. 2860 o "Specify DSCP field", "Disable Nagle algorithm", "Enable and 2861 configure a 'Low Extra Delay Background Transfer'": As suggested 2862 in Section 5.5 of [I-D.ietf-taps-minset], these transport features 2863 are collectively offered via the "Capacity Profile" property. 2865 o Close after reliably delivering all remaining data, causing an 2866 event informing the application on the other side: This is offered 2867 by the "Close" Action with slightly changed semantics in line with 2868 the discussion in Section 5.2 of [I-D.ietf-taps-minset]. 2870 o "Abort without delivering remaining data, causing an event 2871 informing the application on the other side" and "Abort without 2872 delivering remaining data, not causing an event informing the 2873 application on the other side": This is offered by the "Abort" 2874 action without promising that this is signaled to the other side. 2875 If it is, a "ConnectionError" Event will fire at the peer. 2877 o "Reliably transfer data, with congestion control", "Reliably 2878 transfer a message, with congestion control" and "Unreliably 2879 transfer a message": Data is tranferred via the "Send" action. 2881 Reliability is controlled via the "Reliable Data Transfer 2882 (Message)" Message property. Transmitting data as a message or 2883 without delimiters is controlled via Message Framers. The choice 2884 of congestion control is provided via the "Congestion control" 2885 property. 2887 o Configurable Message Reliability: The "Lifetime" Message Property 2888 implements a time-based way to configure message reliability. 2890 o "Ordered message delivery (potentially slower than unordered)" and 2891 "Unordered message delivery (potentially faster than ordered)": 2892 The two transport features are controlled via the Message Property 2893 "Ordered". 2895 o Request not to delay the acknowledgement (SACK) of a message: 2896 Should the protocol support it, this is one of the transport 2897 features the transport system can use when an application uses the 2898 "Capacity Profile" Property with value "Low Latency/Interactive". 2900 o Receive data (with no message delimiting): "Received" Event 2901 without using a Message Framer. 2903 o Receive a message: "Received" Event, using Message Framers. 2905 o Information about partial message arrival: "ReceivedPartial" 2906 Event. 2908 o Notification of send failures: "Expired" and "SendError" Events. 2910 o Notification that the stack has no more user data to send: 2911 Applications can obtain this information via the "Sent" Event. 2913 o Notification to a receiver that a partial message delivery has 2914 been aborted: "ReceiveError" Event. 2916 Authors' Addresses 2918 Brian Trammell (editor) 2919 Google 2920 Gustav-Gull-Platz 1 2921 8004 Zurich 2922 Switzerland 2924 Email: ietf@trammell.ch 2925 Michael Welzl (editor) 2926 University of Oslo 2927 PO Box 1080 Blindern 2928 0316 Oslo 2929 Norway 2931 Email: michawe@ifi.uio.no 2933 Theresa Enghardt 2934 TU Berlin 2935 Marchstrasse 23 2936 10587 Berlin 2937 Germany 2939 Email: theresa@inet.tu-berlin.de 2941 Godred Fairhurst 2942 University of Aberdeen 2943 Fraser Noble Building 2944 Aberdeen, AB24 3UE 2945 Scotland 2947 Email: gorry@erg.abdn.ac.uk 2948 URI: http://www.erg.abdn.ac.uk/ 2950 Mirja Kuehlewind 2951 ETH Zurich 2952 Gloriastrasse 35 2953 8092 Zurich 2954 Switzerland 2956 Email: mirja.kuehlewind@tik.ee.ethz.ch 2958 Colin Perkins 2959 University of Glasgow 2960 School of Computing Science 2961 Glasgow G12 8QQ 2962 United Kingdom 2964 Email: csp@csperkins.org 2965 Philipp S. Tiesel 2966 TU Berlin 2967 Einsteinufer 25 2968 10587 Berlin 2969 Germany 2971 Email: philipp@tiesel.net 2973 Chris Wood 2974 Apple Inc. 2975 One Apple Park Way 2976 Cupertino, California 95014 2977 United States of America 2979 Email: cawood@apple.com 2981 Tommy Pauly 2982 Apple Inc. 2983 One Apple Park Way 2984 Cupertino, California 95014 2985 United States of America 2987 Email: tpauly@apple.com