idnits 2.17.1 draft-ietf-taps-interface-03.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 (March 11, 2019) is 1870 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 2335, but no explicit reference was found in the text == Outdated reference: A later version (-19) exists of draft-ietf-taps-arch-02 == Outdated reference: A later version (-12) exists of draft-ietf-taps-transport-security-06 -- 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: 1 error (**), 0 flaws (~~), 4 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 TAPS Working Group B. Trammell, Ed. 3 Internet-Draft Google 4 Intended status: Standards Track M. Welzl, Ed. 5 Expires: September 12, 2019 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 Apple Inc. 18 March 11, 2019 20 An Abstract Application Layer Interface to Transport Services 21 draft-ietf-taps-interface-03 23 Abstract 25 This document describes an abstract programming interface to the 26 transport layer, following the Transport Services Architecture. It 27 supports the asynchronous, atomic transmission of messages over 28 transport protocols and network paths dynamically selected at 29 runtime. It is intended to replace the traditional BSD sockets API 30 as the lowest common denominator interface to the transport layer, in 31 an environment where endpoints have multiple interfaces and potential 32 transport protocols to select from. 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at https://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on September 12, 2019. 50 Copyright Notice 52 Copyright (c) 2019 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (https://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 68 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 5 69 3. Interface Design Principles . . . . . . . . . . . . . . . . . 6 70 4. API Summary . . . . . . . . . . . . . . . . . . . . . . . . . 7 71 4.1. Usage Examples . . . . . . . . . . . . . . . . . . . . . 7 72 4.1.1. Server Example . . . . . . . . . . . . . . . . . . . 8 73 4.1.2. Client Example . . . . . . . . . . . . . . . . . . . 9 74 4.1.3. Peer Example . . . . . . . . . . . . . . . . . . . . 10 75 4.2. Transport Properties . . . . . . . . . . . . . . . . . . 11 76 4.2.1. Transport Property Names . . . . . . . . . . . . . . 12 77 4.2.2. Transport Property Types . . . . . . . . . . . . . . 13 78 4.3. Scope of the Interface Definition . . . . . . . . . . . . 13 79 5. Pre-Establishment Phase . . . . . . . . . . . . . . . . . . . 14 80 5.1. Specifying Endpoints . . . . . . . . . . . . . . . . . . 14 81 5.2. Specifying Transport Properties . . . . . . . . . . . . . 16 82 5.2.1. Reliable Data Transfer (Connection) . . . . . . . . . 18 83 5.2.2. Preservation of Message Boundaries . . . . . . . . . 18 84 5.2.3. Configure per-Message reliability . . . . . . . . . . 18 85 5.2.4. Preservation of data ordering . . . . . . . . . . . . 18 86 5.2.5. Use 0-RTT session establishment with an idempotent 87 Message . . . . . . . . . . . . . . . . . . . . . . . 19 88 5.2.6. Multistream Connections in Group . . . . . . . . . . 19 89 5.2.7. Control checksum coverage on sending . . . . . . . . 19 90 5.2.8. Control checksum coverage on receiving . . . . . . . 19 91 5.2.9. Congestion control . . . . . . . . . . . . . . . . . 19 92 5.2.10. Interface Instance or Type . . . . . . . . . . . . . 20 93 5.2.11. Provisioning Domain Instance or Type . . . . . . . . 21 94 5.2.12. Parallel Use of Multiple Paths . . . . . . . . . . . 21 95 5.2.13. Direction of communication . . . . . . . . . . . . . 22 96 5.2.14. Notification of excessive retransmissions . . . . . . 22 97 5.2.15. Notification of ICMP soft error message arrival . . . 22 98 5.3. Specifying Security Parameters and Callbacks . . . . . . 22 99 5.3.1. Pre-Connection Parameters . . . . . . . . . . . . . . 23 100 5.3.2. Connection Establishment Callbacks . . . . . . . . . 24 101 6. Establishing Connections . . . . . . . . . . . . . . . . . . 24 102 6.1. Active Open: Initiate . . . . . . . . . . . . . . . . . . 24 103 6.2. Passive Open: Listen . . . . . . . . . . . . . . . . . . 26 104 6.3. Peer-to-Peer Establishment: Rendezvous . . . . . . . . . 27 105 6.4. Connection Groups . . . . . . . . . . . . . . . . . . . . 28 106 7. Sending Data . . . . . . . . . . . . . . . . . . . . . . . . 29 107 7.1. Basic Sending . . . . . . . . . . . . . . . . . . . . . . 29 108 7.2. Send Events . . . . . . . . . . . . . . . . . . . . . . . 30 109 7.2.1. Sent . . . . . . . . . . . . . . . . . . . . . . . . 30 110 7.2.2. Expired . . . . . . . . . . . . . . . . . . . . . . . 30 111 7.2.3. SendError . . . . . . . . . . . . . . . . . . . . . . 31 112 7.3. Message Properties . . . . . . . . . . . . . . . . . . . 31 113 7.3.1. Lifetime . . . . . . . . . . . . . . . . . . . . . . 32 114 7.3.2. Priority . . . . . . . . . . . . . . . . . . . . . . 32 115 7.3.3. Ordered . . . . . . . . . . . . . . . . . . . . . . . 33 116 7.3.4. Idempotent . . . . . . . . . . . . . . . . . . . . . 33 117 7.3.5. Final . . . . . . . . . . . . . . . . . . . . . . . . 33 118 7.3.6. Corruption Protection Length . . . . . . . . . . . . 34 119 7.3.7. Reliable Data Transfer (Message) . . . . . . . . . . 34 120 7.3.8. Message Capacity Profile Override . . . . . . . . . . 34 121 7.3.9. Singular Transmission . . . . . . . . . . . . . . . . 35 122 7.4. Partial Sends . . . . . . . . . . . . . . . . . . . . . . 35 123 7.5. Batching Sends . . . . . . . . . . . . . . . . . . . . . 36 124 7.6. Send on Active Open: InitiateWithSend . . . . . . . . . . 36 125 7.7. Sender-side Framing . . . . . . . . . . . . . . . . . . . 37 126 8. Receiving Data . . . . . . . . . . . . . . . . . . . . . . . 37 127 8.1. Enqueuing Receives . . . . . . . . . . . . . . . . . . . 37 128 8.2. Receive Events . . . . . . . . . . . . . . . . . . . . . 38 129 8.2.1. Received . . . . . . . . . . . . . . . . . . . . . . 38 130 8.2.2. ReceivedPartial . . . . . . . . . . . . . . . . . . . 39 131 8.2.3. ReceiveError . . . . . . . . . . . . . . . . . . . . 39 132 8.3. Message Receive Context . . . . . . . . . . . . . . . . . 40 133 8.3.1. ECN . . . . . . . . . . . . . . . . . . . . . . . . . 40 134 8.3.2. Early Data . . . . . . . . . . . . . . . . . . . . . 40 135 8.3.3. Receiving Final Messages . . . . . . . . . . . . . . 40 136 8.4. Receiver-side De-framing over Stream Protocols . . . . . 41 137 9. Managing Connections . . . . . . . . . . . . . . . . . . . . 41 138 9.1. Generic Connection Properties . . . . . . . . . . . . . . 43 139 9.1.1. Retransmission threshold before excessive 140 retransmission notification . . . . . . . . . . . . . 43 141 9.1.2. Required minimum coverage of the Corruption 142 Protection for receiving . . . . . . . . . . . . . . 43 143 9.1.3. Priority (Connection) . . . . . . . . . . . . . . . . 44 144 9.1.4. Timeout for aborting Connection . . . . . . . . . . . 44 145 9.1.5. Connection group transmission scheduler . . . . . . . 44 146 9.1.6. Maximum message size concurrent with Connection 147 establishment . . . . . . . . . . . . . . . . . . . . 44 148 9.1.7. Maximum Message size before fragmentation or 149 segmentation . . . . . . . . . . . . . . . . . . . . 44 150 9.1.8. Maximum Message size on send . . . . . . . . . . . . 45 151 9.1.9. Maximum Message size on receive . . . . . . . . . . . 45 152 9.1.10. Capacity Profile . . . . . . . . . . . . . . . . . . 45 153 9.1.11. Bounds on Send or Receive Rate . . . . . . . . . . . 47 154 9.1.12. TCP-specific Property: User Timeout . . . . . . . . . 47 155 9.2. Soft Errors . . . . . . . . . . . . . . . . . . . . . . . 47 156 9.3. Excessive retransmissions . . . . . . . . . . . . . . . . 48 157 10. Connection Termination . . . . . . . . . . . . . . . . . . . 48 158 11. Connection State and Ordering of Operations and Events . . . 48 159 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 50 160 13. Security Considerations . . . . . . . . . . . . . . . . . . . 50 161 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 50 162 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 50 163 15.1. Normative References . . . . . . . . . . . . . . . . . . 50 164 15.2. Informative References . . . . . . . . . . . . . . . . . 51 165 Appendix A. Additional Properties . . . . . . . . . . . . . . . 53 166 A.1. Experimental Transport Properties . . . . . . . . . . . . 53 167 A.1.1. Cost Preferences . . . . . . . . . . . . . . . . . . 53 168 Appendix B. Sample API definition in Go . . . . . . . . . . . . 54 169 Appendix C. Relationship to the Minimal Set of Transport 170 Services for End Systems . . . . . . . . . . . . . . 54 171 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 58 173 1. Introduction 175 The BSD Unix Sockets API's SOCK_STREAM abstraction, by bringing 176 network sockets into the UNIX programming model, allowing anyone who 177 knew how to write programs that dealt with sequential-access files to 178 also write network applications, was a revolution in simplicity. The 179 simplicity of this API is a key reason the Internet won the protocol 180 wars of the 1980s. SOCK_STREAM is tied to the Transmission Control 181 Protocol (TCP), specified in 1981 [RFC0793]. TCP has scaled 182 remarkably well over the past three and a half decades, but its total 183 ubiquity has hidden an uncomfortable fact: the network is not really 184 a file, and stream abstractions are too simplistic for many modern 185 application programming models. 187 In the meantime, the nature of Internet access, and the variety of 188 Internet transport protocols, is evolving. The challenges that new 189 protocols and access paradigms present to the sockets API and to 190 programming models based on them inspire the design principles of a 191 new approach, which we outline in Section 3. 193 As a first step to realizing this design, [I-D.ietf-taps-arch] 194 describes a high-level architecture for transport services. This 195 document builds a modern abstract programming interface atop this 196 architecture, deriving specific path and protocol selection 197 properties and supported transport features from the analysis 198 provided in [RFC8095], [I-D.ietf-taps-minset], and 199 [I-D.ietf-taps-transport-security]. 201 2. Terminology and Notation 203 This API is described in terms of Objects, which an application can 204 interact with; Actions the application can perform on these Objects; 205 Events, which an Object can send to an application asynchronously; 206 and Parameters associated with these Actions and Events. 208 The following notations, which can be combined, are used in this 209 document: 211 o An Action creates an Object: 213 Object := Action() 215 o An Action creates an array of Objects: 217 []Object := Action() 219 o An Action is performed on an Object: 221 Object.Action() 223 o An Object sends an Event: 225 Object -> Event<> 227 o An Action takes a set of Parameters; an Event contains a set of 228 Parameters. Action parameters whose names are suffixed with a 229 question mark are optional. 231 Action(param0, param1?, ...) / Event 233 Actions associated with no Object are Actions on the abstract 234 interface itself; they are equivalent to Actions on a per-application 235 global context. 237 How these abstract concepts map into concrete implementations of this 238 API in a given language on a given platform is largely dependent on 239 the features of the language and the platform. Actions could be 240 implemented as functions or method calls, for instance, and Events 241 could be implemented via callbacks, communicating sequential 242 processes, or other asynchronous calling conventions. The method for 243 dispatching and handling Events is left as an implementation detail, 244 with the caveat that the interface for receiving Messages must 245 require the application to invoke the Connection.Receive() Action 246 once per Message to be received (see Section 8). 248 This specification treats Events and errors similarly. Errors, just 249 as any other Events, may occur asynchronously in network 250 applications. However, it is recommended that implementations of 251 this interface also return errors immediately, according to the error 252 handling idioms of the implementation platform, for errors which can 253 be immediately detected, such as inconsistency in Transport 254 Properties. 256 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 257 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 258 "OPTIONAL" in this document are to be interpreted as described in BCP 259 14 [RFC2119] [RFC8174] when, and only when, they appear in all 260 capitals, as shown here. 262 3. Interface Design Principles 264 The design of the interface specified in this document is based on a 265 set of princples, themselves an elaboration on the architectural 266 design principles defined in [I-D.ietf-taps-arch]. The interface 267 defined in this document provides: 269 o A single interface to a variety of transport protocols to be used 270 in a variety of application design patterns, independent of the 271 properties of the application and the Protocol Stacks that will be 272 used at runtime, such that all common specialized features of 273 these protocol stacks are made available to the application as 274 necessary in a transport-independent way, to enable applications 275 written to a single API to make use of transport protocols in 276 terms of the features they provide; 278 o Message- as opposed to stream-orientation, using application- 279 assisted framing and deframing where the underlying transport does 280 not provide these; 282 o Asynchronous Connection establishment, transmission, and 283 reception, allowing concurrent operations during establishment and 284 supporting event-driven application interactions with the 285 transport layer, in line with developments in modern platforms and 286 programming languages; 288 o Explicit support for security properties as first-order transport 289 features, and for long-term caching of cryptographic identities 290 and parameters for associations among endpoints; and 292 o Explicit support for multistreaming and multipath transport 293 protocols, and the grouping of related Connections into Connection 294 Groups through cloning of Connections, to allow applications to 295 take full advantage of new transport protocols supporting these 296 features. 298 4. API Summary 300 The Transport Services Interface is the basic common abstract 301 application programming interface to the Transport Services 302 Architecture defined in [I-D.ietf-taps-arch]. 304 An application primarily interacts with this interface through two 305 Objects, Preconnections and Connections. A Preconnection represents 306 a set of properties and constraints on the selection and 307 configuration of paths and protocols to establish a Connection with a 308 remote endpoint. A Connection represents a transport Protocol Stack 309 on which data can be sent to and/or received from a remote endpoint 310 (i.e., depending on the kind of transport, connections can be bi- 311 directional or unidirectional). Connections can be created from 312 Preconnections in three ways: by initiating the Preconnection (i.e., 313 actively opening, as in a client), through listening on the 314 Preconnection (i.e., passively opening, as in a server), or 315 rendezvousing on the Preconnection (i.e. peer to peer 316 establishment). 318 Once a Connection is established, data can be sent on it in the form 319 of Messages. The interface supports the preservation of message 320 boundaries both via explicit Protocol Stack support, and via 321 application support through a deframing callback which finds message 322 boundaries in a stream. Messages are received asynchronously through 323 a callback registered by the application. Errors and other 324 notifications also happen asynchronously on the Connection. 326 Section 5, Section 6, Section 7, Section 8, and Section 10 describe 327 the details of application interaction with Objects through Actions 328 and Events in each phase of a Connection, following the phases 329 described in [I-D.ietf-taps-arch]. 331 4.1. Usage Examples 333 The following usage examples illustrate how an application might use 334 a Transport Services Interface to: 336 o Act as a server, by listening for incoming connections, receiving 337 requests, and sending responses, see Section 4.1.1. 339 o Act as a client, by connecting to a remote endpoint using 340 Initiate, sending requests, and receiving responses, see 341 Section 4.1.2. 343 o Act as a peer, by connecting to a remote endpoint using Rendezvous 344 while simultaneously waiting for incoming Connections, sending 345 Messages, and receiving Messages, see Section 4.1.3. 347 The examples in this section presume that a transport protocol is 348 available between the endpoints which provides Reliable Data 349 Transfer, Preservation of data ordering, and Preservation of Message 350 Boundaries. In this case, the application can choose to receive only 351 complete messages. 353 If none of the available transport protocols provides Preservation of 354 Message Boundaries, but there is a transport protocol which provides 355 a reliable ordered octet stream, an application may receive this 356 octet stream as partial Messages and transform it into application- 357 layer Messages. Alternatively, an application may provide a 358 Deframer, which is a function that transforms an octet stream into a 359 sequence of Messages, see Section 8.4. 361 4.1.1. Server Example 363 This is an example of how an application might listen for incoming 364 Connections using the Transport Services Interface, receive a 365 request, and send a response. 367 LocalSpecifier := NewLocalEndpoint() 368 LocalSpecifier.WithInterface("any") 369 LocalSpecifier.WithService("https") 371 TransportProperties := NewTransportProperties() 372 TransportProperties.Require(preserve-msg-boundaries) 373 // Reliable Data Transfer and Preserve Order are Required by default 375 SecurityParameters := NewSecurityParameters() 376 SecurityParameters.AddIdentity(identity) 377 SecurityParameters.AddPrivateKey(privateKey, publicKey) 379 // Specifying a remote endpoint is optional when using Listen() 380 Preconnection := NewPreconnection(LocalSpecifier, 381 None, 382 TransportProperties, 383 SecurityParameters) 385 Preconnection.Listen() 387 Preconnection -> ConnectionReceived 389 // Only receive complete messages 390 Connection.Receive() 392 Connection -> Received(messageDataRequest, messageContext) 394 Connection.Send(messageDataResponse) 396 Connection.Close() 398 // Stop listening for incoming Connections 399 Preconnection.Stop() 401 4.1.2. Client Example 403 This is an example of how an application might connect to a remote 404 application using the Transport Services Interface, send a request, 405 and receive a response. 407 RemoteSpecifier := NewRemoteEndpoint() 408 RemoteSpecifier.WithHostname("example.com") 409 RemoteSpecifier.WithService("https") 411 TransportProperties := NewTransportProperties() 412 TransportProperties.Require(preserve-msg-boundaries) 413 // Reliable Data Transfer and Preserve Order are Required by default 415 SecurityParameters := NewSecurityParameters() 416 TrustCallback := New Callback({ 417 // Verify identity of the remote endpoint, return the result 418 }) 419 SecurityParameters.SetTrustVerificationCallback(TrustCallback) 421 // Specifying a local endpoint is optional when using Initiate() 422 Preconnection := NewPreconnection(None, 423 RemoteSpecifier, 424 TransportPreperties, 425 SecurityParameters) 427 Connection := Preconnection.Initiate() 429 Connection -> Ready<> 431 Connection.Send(messageDataRequest) 433 // Only receive complete messages 434 Connection.Receive() 436 Connection -> Received(messageDataResponse, messageContext) 438 Connection.Close() 440 4.1.3. Peer Example 442 This is an example of how an application might establish a connection 443 with a peer using Rendezvous(), send a Message, and receive a 444 Message. 446 LocalSpecifier := NewLocalEndpoint() 447 LocalSpecifier.WithPort(9876) 449 RemoteSpecifier := NewRemoteEndpoint() 450 RemoteSpecifier.WithHostname("example.com") 451 RemoteSpecifier.WithPort(9877) 453 TransportProperties := NewTransportProperties() 454 TransportProperties.Require(preserve-msg-boundaries) 455 // Reliable Data Transfer and Preserve Order are Required by default 457 SecurityParameters := NewSecurityParameters() 458 SecurityParameters.AddIdentity(identity) 459 SecurityParameters.AddPrivateKey(privateKey, publicKey) 461 TrustCallback := New Callback({ 462 // Verify identity of the remote endpoint, return the result 463 }) 464 SecurityParameters.SetTrustVerificationCallback(trustCallback) 466 // Both local and remote endpoint must be specified 467 Preconnection := NewPreconnection(LocalSpecifier, 468 RemoteSpecifier, 469 TransportPreperties, 470 SecurityParameters) 472 Preconnection.Rendezvous() 474 Preconnection -> RendezvousDone 476 Connection.Send(messageDataRequest) 478 // Only receive complete messages 479 Connection.Receive() 481 Connection -> Received(messageDataResponse, messageContext) 483 Connection.Close() 485 4.2. Transport Properties 487 Each application using the Transport Services Interface declares its 488 preferences for how the transport service should operate using 489 properties at each stage of the lifetime of a connection. During 490 pre-establishment, Selection Properties (see Section 5.2) are used to 491 specify which paths and protocol stacks can be used and are preferred 492 by the application, and Connection Properties (see Section 9.1) can 493 be used to influence decisions made during establishment and to fine- 494 tune the eventually established connection. These Connection 495 Properties can also be used later, to monitor and fine-tune 496 established connections. The behavior of the selected protocol 497 stack(s) when sending Messages is controlled by Message Properties 498 (see Section 7.3). 500 Collectively, Selection, Connection, and Message Properties can be 501 referred to as Transport Properties. All Transport Properties, 502 regardless of the phase in which they are used, are organized within 503 a single namespace. This enables setting them as defaults in earlier 504 stages and querying them in later stages: - Connection Properties can 505 be set on Preconnections - Message Properties can be set on 506 Preconnections and Connections - The effect of Selection Properties 507 can be queried on Connections and Messages 509 Note that Configuring Connection Properties and Message Properties on 510 Preconnections is preferred over setting them later. Connection 511 Properties specified early on may be used as additional input to the 512 selection process. Also note that Protocol Specific Properties, see 513 Section 4.2.1, should not be used as an input to the selection 514 process. 516 4.2.1. Transport Property Names 518 Transport Properties are referred to by property names. These names 519 are lower-case strings whereby words are separated by hyphens. These 520 names serve two purposes: 522 o Allow different components of a TAPS implementation to pass 523 Transport Properties, e.g., between a language frontend and a 524 policy manager. 526 o Make code of different TAPS implementations look similar. 528 Transport Property Names are hierarchically organized in the form 529 [.]. 531 o The Namespace part is empty for well known, generic properties, 532 i.e., for properties defined by an RFC which are not protocol 533 specific. 535 o Protocol Specific Properties must use the protocol acronym as 536 Namespace, e.g., "tcp" for TCP specific Transport Properties. For 537 IETF protocols, property names under these namespaces should be 538 defined in an RFC. 540 o Vendor or implementation specific properties must use a a string 541 identifying the vendor or implementation as Namespace. 543 4.2.2. Transport Property Types 545 Transport Properties can have one of a set of data types: 547 o Boolean: can take the values "true" and "false"; representation is 548 implementation-dependent. 550 o Integer: can take positive or negative numeric integer values; 551 range and representation is implementation-dependent. 553 o Numeric: can take positive or negative numeric values; range and 554 representation is implementation-dependent. 556 o Enumeration: can take one value of a finite set of values, 557 dependent on the property itself. The representation is 558 implementation dependent; however, implementations MUST provide a 559 method for the application to determine the entire set of possible 560 values for each property. 562 o Preference: can take one of five values (Prohibit, Avoid, Ignore, 563 Prefer, Require) for the level of preference of a given property 564 during protocol selection; see Section 5.2. 566 4.3. Scope of the Interface Definition 568 This document defines a language- and platform-independent interface 569 to a Transport Services system. Given the wide variety of languages 570 and language conventions used to write applications that use the 571 transport layer to connect to other applications over the Internet, 572 this independence makes this interface necessarily abstract. While 573 there is no interoperability benefit to tightly defining how the 574 interface be presented to application programmers in diverse 575 platforms, maintaining the "shape" of the abstract interface across 576 these platforms reduces the effort for programmers who learn the 577 transport services interface to apply their knowledge in multiple 578 platforms. We therefore make the following recommendations: 580 o Actions, Events, and Errors in implementations of this interface 581 SHOULD carry the names given for them in the document, subject to 582 capitalization and punctuation conventions in the language of the 583 implementation, unless the implementation itself uses different 584 names for substantially equivalent objects for networking by 585 convention. 587 o Implementations of this interface SHOULD implement each Selection 588 Property, Connection Property, and Message Context Property 589 specified in this document, exclusive of appendices, even if said 590 implementation is a non-operation, e.g. because transport 591 protocols implementing a given Property are not available on the 592 platform. 594 o Implementations may use other representations for Transport 595 Property Names, e.g., by providing constants or static singleton 596 objects, but should provide a straight-forward mapping between 597 their representation and the property names specified here. 599 5. Pre-Establishment Phase 601 The pre-establishment phase allows applications to specify properties 602 for the Connections they are about to make, or to query the API about 603 potential connections they could make. 605 A Preconnection Object represents a potential Connection. It has 606 state that describes properties of a Connection that might exist in 607 the future. This state comprises Local Endpoint and Remote Endpoint 608 Objects that denote the endpoints of the potential Connection (see 609 Section 5.1), the Selection Properties (see Section 5.2), any 610 preconfigured Connection Properties (Section 9.1), and the security 611 parameters (see Section 5.3): 613 Preconnection := NewPreconnection(LocalEndpoint, 614 RemoteEndpoint, 615 TransportProperties, 616 SecurityParams) 618 The Local Endpoint MUST be specified if the Preconnection is used to 619 Listen() for incoming Connections, but is OPTIONAL if it is used to 620 Initiate() connections. The Remote Endpoint MUST be specified if the 621 Preconnection is used to Initiate() Connections, but is OPTIONAL if 622 it is used to Listen() for incoming Connections. The Local Endpoint 623 and the Remote Endpoint MUST both be specified if a peer-to-peer 624 Rendezvous is to occur based on the Preconnection. 626 Framers (see Section 7.7) and deframers (see Section 8.4), if 627 necessary, should be bound to the Preconnection during pre- 628 establishment. 630 5.1. Specifying Endpoints 632 The transport services API uses the Local Endpoint and Remote 633 Endpoint types to refer to the endpoints of a transport connection. 634 Subtypes of these represent various different types of endpoint 635 identifiers, such as IP addresses, DNS names, and interface names, as 636 well as port numbers and service names. 638 RemoteSpecifier := NewRemoteEndpoint() 639 RemoteSpecifier.WithHostname("example.com") 640 RemoteSpecifier.WithService("https") 642 RemoteSpecifier := NewRemoteEndpoint() 643 RemoteSpecifier.WithIPv6Address(2001:db8:4920:e29d:a420:7461:7073:0a) 644 RemoteSpecifier.WithPort(443) 646 RemoteSpecifier := NewRemoteEndpoint() 647 RemoteSpecifier.WithIPv4Address(192.0.2.21) 648 RemoteSpecifier.WithPort(443) 650 LocalSpecifier := NewLocalEndpoint() 651 LocalSpecifier.WithInterface("en0") 652 LocalSpecifier.WithPort(443) 654 LocalSpecifier := NewLocalEndpoint() 655 LocalSpecifier.WithStunServer(address, port, credentials) 657 Implementations may also support additional endpoint representations 658 and provide a single NewEndpoint() call that takes different endpoint 659 representations. 661 Multiple endpoint identifiers can be specified for each Local 662 Endpoint and Remote Endpoint. For example, a Local Endpoint could be 663 configured with two interface names, or a Remote Endpoint could be 664 specified via both IPv4 and IPv6 addresses. These multiple 665 identifiers refer to the same transport endpoint. 667 The transport services API resolves names internally, when the 668 Initiate(), Listen(), or Rendezvous() method is called establish a 669 Connection. The API explicitly does not require the application to 670 resolve names, though there is a tradeoff between early and late 671 binding of addresses to names. Early binding allows the API 672 implementation to reduce connection setup latency, at the cost of 673 potentially limited scope for alternate path discovery during 674 Connection establishment, as well as potential additional information 675 leakage about application interest when used with a resolution method 676 (such as DNS without TLS) which does not protect query 677 confidentiality. 679 The Resolve() action on Preconnection can be used by the application 680 to force early binding when required, for example with some Network 681 Address Translator (NAT) traversal protocols (see Section 6.3). 683 5.2. Specifying Transport Properties 685 A Preconnection Object holds properties reflecting the application's 686 requirements and preferences for the transport. These include 687 Selection Properties for selecting protocol stacks and paths, as well 688 as Connection Properties for configuration of the detailed operation 689 of the selected Protocol Stacks. 691 The protocol(s) and path(s) selected as candidates during 692 establishment are determined and configured using these properties. 693 Since there could be paths over which some transport protocols are 694 unable to operate, or remote endpoints that support only specific 695 network addresses or transports, transport protocol selection is 696 necessarily tied to path selection. This may involve choosing 697 between multiple local interfaces that are connected to different 698 access networks. 700 Most Selection Properties are represented as preferences, which can 701 have one of five preference levels: 703 +------------+------------------------------------------------------+ 704 | Preference | Effect | 705 +------------+------------------------------------------------------+ 706 | Require | Select only protocols/paths providing the property, | 707 | | fail otherwise | 708 | | | 709 | Prefer | Prefer protocols/paths providing the property, | 710 | | proceed otherwise | 711 | | | 712 | Ignore | No preference | 713 | | | 714 | Avoid | Prefer protocols/paths not providing the property, | 715 | | proceed otherwise | 716 | | | 717 | Prohibit | Select only protocols/paths not providing the | 718 | | property, fail otherwise | 719 +------------+------------------------------------------------------+ 721 In addition, the pseudo-level "Default" can be used to reset the 722 property to the default level used by the implementation. This level 723 will never show up when queuing the value of a preference - the 724 effective preference must be returned instead. 726 Internally, the transport system will first exclude all protocols and 727 paths that match a Prohibit, then exclude all protocols and paths 728 that do not match a Require, then sort candidates according to 729 Preferred properties, and then use Avoided properties as a 730 tiebreaker. Selection Properties which select paths take preference 731 over those which select protocols. For example, if an application 732 indicates a preference for a specific path by specifying an 733 interface, but also a preference for a protocol not available on this 734 path, the transport system will try the path first, ignoring the 735 preference. 737 Both Selection and Connection Properties can be added to a 738 Preconnection to configure the selection process, and to further 739 configure the eventually selected protocol stack(s). They are 740 collected into a TransportProperties object to be passed into a 741 Preconnection object: 743 TransportProperties := NewTransportProperties() 745 Individual properties are then added to the TransportProperties 746 Object: 748 TransportProperties.Add(property, value) 750 Selection Properties can be added to a TransportProperties object 751 using special actions for each preference level i.e, 752 "TransportProperties.Add(some_property, avoid)" is equivalent to 753 "TransportProperties.Avoid(some_property)": 755 TransportProperties.Require(property) 756 TransportProperties.Prefer(property) 757 TransportProperties.Ignore(property) 758 TransportProperties.Avoid(property) 759 TransportProperties.Prohibit(property) 760 TransportProperties.Default(property) 762 For an existing Connection, the Transport Properties can be queried 763 any time by using the following call on the Connection Object: 765 TransportProperties := Connection.GetTransportProperties() 767 A Connection gets its Transport Properties either by being explicitly 768 configured via a Preconnection, by configuration after establishment, 769 or by inheriting them from an antecedent via cloning; see Section 6.4 770 for more. 772 Section 9.1 provides a list of Connection Properties, while Selection 773 Properties are listed in the subsections below. Note that many 774 properties are only considered during establishment, and can not be 775 changed after a Connection is established; however, they can be 776 queried. Querying a Selection Property after establishment yields 777 the value Required for properties of the selected protocol and path, 778 Avoid for properties avoided during selection, and Ignore for all 779 other properties. 781 An implementation of this interface must provide sensible defaults 782 for Selection Properties. The recommended defaults given for each 783 property below represent a configuration that can be implemented over 784 TCP. An alternate set of default Protocol Selection Properties would 785 represent a configuration that can be implemented over UDP. 787 5.2.1. Reliable Data Transfer (Connection) 789 Name: reliability 791 This property specifies whether the application needs to use a 792 transport protocol that ensures that all data is received on the 793 other side without corruption. This also entails being notified when 794 a Connection is closed or aborted. The recommended default is to 795 Require Reliable Data Transfer. 797 5.2.2. Preservation of Message Boundaries 799 Name: preserve-msg-boundaries 801 This property specifies whether the application needs or prefers to 802 use a transport protocol that preserves message boundaries. The 803 recommended default is to Prefer Preservation of Message Boundaries. 805 5.2.3. Configure per-Message reliability 807 Name: per-msg-reliability 809 This property specifies whether an application considers it useful to 810 indicate its reliability requirements on a per-Message basis. This 811 property applies to Connections and Connection Groups. The 812 recommended default is to Ignore this option. 814 5.2.4. Preservation of data ordering 816 Name: preserve-order 818 This property specifies whether the application wishes to use a 819 transport protocol that can ensure that data is received by the 820 application on the other end in the same order as it was sent. The 821 recommended default is to Require Preservation of data ordering. 823 5.2.5. Use 0-RTT session establishment with an idempotent Message 825 Name: zero-rtt-msg 827 This property specifies whether an application would like to supply a 828 Message to the transport protocol before Connection establishment, 829 which will then be reliably transferred to the other side before or 830 during Connection establishment, potentially multiple times. See 831 also Section 7.3.4. The recommended default is to Prefer this 832 option. 834 5.2.6. Multistream Connections in Group 836 Name: multistreaming 838 This property specifies that the application would prefer multiple 839 Connections within a Connection Group to be provided by streams of a 840 single underlying transport connection where possible. The 841 recommended default is to Prefer have this option. 843 5.2.7. Control checksum coverage on sending 845 Name: per-msg-checksum-len-send 847 This property specifies whether the application considers it useful 848 to enable, disable, or configure a checksum when sending a Message. 849 The recommended default is to Ignore this option. 851 5.2.8. Control checksum coverage on receiving 853 Name: per-msg-checksum-len-recv 855 This property specifies whether the application considers it useful 856 configure whether to require a checksum or not when receiving. The 857 recommended default is to Ignore this option. 859 5.2.9. Congestion control 861 Name: congestion-control 863 This property specifies whether the application would like the 864 Connection to be congestion controlled or not. Note that if a 865 Connection is not congestion controlled, an application using such a 866 Connection should itself perform congestion control in accordance 867 with [RFC2914]. Also note that reliability is usually combined with 868 congestion control in protocol implementations, rendering "reliable 869 but not congestion controlled" a request that is unlikely to succeed. 871 The recommended default is to Require that the Connection is 872 congestion controlled. 874 5.2.10. Interface Instance or Type 876 Name: interface 878 Type: Set (Preference, Enumeration) 880 This property allows the application to select which specific network 881 interfaces or categories of interfaces it wants to "Require", 882 "Prohibit", "Prefer", or "Avoid". 884 In contrast to other Selection Properties, this property is a tuple 885 of an (Enumerated) interface identifier and a preference, and can 886 either be implemented directly as such, or for making one preference 887 available for each interface and interface type available on the 888 system. 890 Note that marking a specific interface as "Required" strictly limits 891 path selection to a single interface, and leads to less flexible and 892 resilient connection establishment. 894 The set of valid interface types is implementation- and system- 895 specific. For example, on a mobile device, there may be "Wi-Fi" and 896 "Cellular" interface types available; whereas on a desktop computer, 897 there may be "Wi-Fi" and "Wired Ethernet" interface types available. 898 Implementations should provide all types that are supported on some 899 system to all systems, in order to allow applications to write 900 generic code. For example, if a single implementation is used on 901 both mobile devices and desktop devices, it should define the 902 "Cellular" interface type for both systems, since an application may 903 want to always "Prohibit Cellular". Note that marking a specific 904 interface type as "Required" limits path selection to a small set of 905 interfaces, and leads to less flexible and resilient connection 906 establishment. 908 The set of interface types is expected to change over time as new 909 access technologies become available. 911 Interface types should not be treated as a proxy for properties of 912 interfaces such as metered or unmetered network access. If an 913 application needs to prohibit metered interfaces, this should be 914 specified via Provisioning Domain attributes (see Section 5.2.11) or 915 another specific property. 917 5.2.11. Provisioning Domain Instance or Type 919 Name: pvd 921 Type: Set (Preference, Enumeration) 923 Similar to interface instances and types (see Section 5.2.10), this 924 property allows the application to control path selection by 925 selecting which specific Provisioning Domains or categories of 926 Provisioning Domains it wants to "Require", "Prohibit", "Prefer", or 927 "Avoid". Provisioning Domains define consistent sets of network 928 properties that may be more specific than network interfaces 929 [RFC7556]. 931 As with interface instances and types, this property is a tuple of an 932 (Enumerated) PvD identifier and a preference, and can either be 933 implemented directly as such, or for making one preference available 934 for each interface and interface type available on the system. 936 The identification of a specific Provisioning Domain (PvD) is defined 937 to be implementation- and system-specific, since there is not a 938 portable standard format for a PvD identitfier. For example, this 939 identifier may be a string name or an integer. As with requiring 940 specific interfaces, requiring a specific PvD strictly limits path 941 selection. 943 Categories or types of PvDs are also defined to be implementation- 944 and system-specific. These may be useful to identify a service that 945 is provided by a PvD. For example, if an application wants to use a 946 PvD that provides a Voice-Over-IP service on a Cellular network, it 947 can use the relevant PvD type to require some PvD that provides this 948 service, without needing to look up a particular instance. While 949 this does restrict path selection, it is broader than requiring 950 specific PvD instances or interface instances, and should be 951 preferred over these options. 953 5.2.12. Parallel Use of Multiple Paths 955 Name: multipath 957 This property specifies whether an application considers it useful to 958 transfer data across multiple paths between the same end hosts. 959 Generally, in most cases, this will improve performance (e.g., 960 achieve greater throughput). One possible side-effect is increased 961 jitter, which may be problematic for delay-sensitive applications. 962 The recommended default is to Prefer this option. 964 5.2.13. Direction of communication 966 Name: direction 968 Type: Enumeration 970 This property specifies whether an application wants to use the 971 connection for sending and/or receiving data. Possible values are: 973 Bidirectional (default): The connection must support sending and 974 receiving data 976 Unidirectional send: The connection must support sending data 978 Unidirectional receive: The connection must support receiving data 980 In case a unidirectional connection is requested, but unidirectional 981 connections are not supported by the transport protocol, the system 982 should fall back to bidirectional transport. 984 5.2.14. Notification of excessive retransmissions 986 Name: :retransmit-notify 988 This property specifies whether an application considers it useful to 989 be informed in case sent data was retransmitted more often than a 990 certain threshold. The recommended default is to Ignore this option. 992 5.2.15. Notification of ICMP soft error message arrival 994 Name: :soft-error-notify 996 This property specifies whether an application considers it useful to 997 be informed when an ICMP error message arrives that does not force 998 termination of a connection. When set to true, received ICMP errors 999 will be available as SoftErrors. Note that even if a protocol 1000 supporting this property is selected, not all ICMP errors will 1001 necessarily be delivered, so applications cannot rely on receiving 1002 them. The recommended default is to Ignore this option. 1004 5.3. Specifying Security Parameters and Callbacks 1006 Most security parameters, e.g., TLS ciphersuites, local identity and 1007 private key, etc., may be configured statically. Others are 1008 dynamically configured during connection establishment. Thus, we 1009 partition security parameters and callbacks based on their place in 1010 the lifetime of connection establishment. Similar to Transport 1011 Properties, both parameters and callbacks are inherited during 1012 cloning (see Section 6.4). 1014 5.3.1. Pre-Connection Parameters 1016 Common parameters such as TLS ciphersuites are known to 1017 implementations. Clients should use common safe defaults for these 1018 values whenever possible. However, as discussed in 1019 [I-D.ietf-taps-transport-security], many transport security protocols 1020 require specific security parameters and constraints from the client 1021 at the time of configuration and actively during a handshake. These 1022 configuration parameters are created as follows: 1024 SecurityParameters := NewSecurityParameters() 1026 Security configuration parameters and sample usage follow: 1028 o Local identity and private keys: Used to perform private key 1029 operations and prove one's identity to the Remote Endpoint. 1030 (Note, if private keys are not available, e.g., since they are 1031 stored in hardware security modules (HSMs), handshake callbacks 1032 must be used. See below for details.) 1034 SecurityParameters.AddIdentity(identity) 1035 SecurityParameters.AddPrivateKey(privateKey, publicKey) 1037 o Supported algorithms: Used to restrict what parameters are used by 1038 underlying transport security protocols. When not specified, 1039 these algorithms should default to known and safe defaults for the 1040 system. Parameters include: ciphersuites, supported groups, and 1041 signature algorithms. 1043 SecurityParameters.AddSupportedGroup(secp256k1) 1044 SecurityParameters.AddCiphersuite(TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256) 1045 SecurityParameters.AddSignatureAlgorithm(ed25519) 1047 o Session cache management: Used to tune cache capacity, lifetime, 1048 re-use, and eviction policies, e.g., LRU or FIFO. Constants and 1049 policies for these interfaces are implementation-specific. 1051 SecurityParameters.SetSessionCacheCapacity(MAX_CACHE_ELEMENTS) 1052 SecurityParameters.SetSessionCacheLifetime(SECONDS_PER_DAY) 1053 SecurityParameters.SetSessionCachePolicy(CachePolicyOneTimeUse) 1055 o Pre-Shared Key import: Used to install pre-shared keying material 1056 established out-of-band. Each pre-shared keying material is 1057 associated with some identity that typically identifies its use or 1058 has some protocol-specific meaning to the Remote Endpoint. 1060 SecurityParameters.AddPreSharedKey(key, identity) 1062 5.3.2. Connection Establishment Callbacks 1064 Security decisions, especially pertaining to trust, are not static. 1065 Once configured, parameters may also be supplied during connection 1066 establishment. These are best handled as client-provided callbacks. 1067 Security handshake callbacks that may be invoked during connection 1068 establishment include: 1070 o Trust verification callback: Invoked when a Remote Endpoint's 1071 trust must be validated before the handshake protocol can proceed. 1073 TrustCallback := NewCallback({ 1074 // Handle trust, return the result 1075 }) 1076 SecurityParameters.SetTrustVerificationCallback(trustCallback) 1078 o Identity challenge callback: Invoked when a private key operation 1079 is required, e.g., when local authentication is requested by a 1080 remote. 1082 ChallengeCallback := NewCallback({ 1083 // Handle challenge 1084 }) 1085 SecurityParameters.SetIdentityChallengeCallback(challengeCallback) 1087 6. Establishing Connections 1089 Before a Connection can be used for data transfer, it must be 1090 established. Establishment ends the pre-establishment phase; all 1091 transport properties and cryptographic parameter specification must 1092 be complete before establishment, as these will be used to select 1093 candidate Paths and Protocol Stacks for the Connection. 1094 Establishment may be active, using the Initiate() Action; passive, 1095 using the Listen() Action; or simultaneous for peer-to-peer, using 1096 the Rendezvous() Action. These Actions are described in the 1097 subsections below. 1099 6.1. Active Open: Initiate 1101 Active open is the Action of establishing a Connection to a Remote 1102 Endpoint presumed to be listening for incoming Connection requests. 1103 Active open is used by clients in client-server interactions. Active 1104 open is supported by this interface through the Initiate Action: 1106 Connection := Preconnection.Initiate(timeout?) 1107 The timeout parameter specifies how long to wait before aborting 1108 Active open. Before calling Initiate, the caller must have populated 1109 a Preconnection Object with a Remote Endpoint specifier, optionally a 1110 Local Endpoint specifier (if not specified, the system will attempt 1111 to determine a suitable Local Endpoint), as well as all properties 1112 necessary for candidate selection. 1114 The Initiate() Action consumes the Preconnection. Once Initiate() 1115 has been called, no further properties may be added to the 1116 Preconnection, and no subsequent establishment call may be made on 1117 the Preconnection. 1119 Once Initiate is called, the candidate Protocol Stack(s) may cause 1120 one or more candidate transport-layer connections to be created to 1121 the specified remote endpoint. The caller may immediately begin 1122 sending Messages on the Connection (see Section 7) after calling 1123 Initate(); note that any idempotent data sent while the Connection is 1124 being established may be sent multiple times or on multiple 1125 candidates. 1127 The following Events may be sent by the Connection after Initiate() 1128 is called: 1130 Connection -> Ready<> 1132 The Ready Event occurs after Initiate has established a transport- 1133 layer connection on at least one usable candidate Protocol Stack over 1134 at least one candidate Path. No Receive Events (see Section 8) will 1135 occur before the Ready Event for Connections established using 1136 Initiate. 1138 Connection -> InitiateError<> 1140 An InitiateError occurs either when the set of transport properties 1141 and security parameters cannot be fulfilled on a Connection for 1142 initiation (e.g. the set of available Paths and/or Protocol Stacks 1143 meeting the constraints is empty) or reconciled with the local and/or 1144 remote endpoints; when the remote specifier cannot be resolved; or 1145 when no transport-layer connection can be established to the remote 1146 endpoint (e.g. because the remote endpoint is not accepting 1147 connections, the application is prohibited from opening a Connection 1148 by the operating system, or the establishment attempt has timed out 1149 for any other reason). 1151 See also Section 7.6 to combine Connection establishment and 1152 transmission of the first message in a single action. 1154 6.2. Passive Open: Listen 1156 Passive open is the Action of waiting for Connections from remote 1157 endpoints, commonly used by servers in client-server interactions. 1158 Passive open is supported by this interface through the Listen 1159 Action: 1161 Preconnection.Listen() 1163 Before calling Listen, the caller must have initialized the 1164 Preconnection during the pre-establishment phase with a Local 1165 Endpoint specifier, as well as all properties necessary for Protocol 1166 Stack selection. A Remote Endpoint may optionally be specified, to 1167 constrain what Connections are accepted. The Listen() Action 1168 consumes the Preconnection. Once Listen() has been called, no 1169 further properties may be added to the Preconnection, and no 1170 subsequent establishment call may be made on the Preconnection. 1172 Listening continues until the global context shuts down, or until the 1173 Stop action is performed on the same Preconnection: 1175 Preconnection.Stop() 1177 After Stop() is called, the preconnection can be disposed of. 1179 Preconnection -> ConnectionReceived 1181 The ConnectionReceived Event occurs when a Remote Endpoint has 1182 established a transport-layer connection to this Preconnection (for 1183 Connection-oriented transport protocols), or when the first Message 1184 has been received from the Remote Endpoint (for Connectionless 1185 protocols), causing a new Connection to be created. The resulting 1186 Connection is contained within the ConnectionReceived event, and is 1187 ready to use as soon as it is passed to the application via the 1188 event. 1190 Preconnection -> ListenError<> 1192 A ListenError occurs either when the Preconnection cannot be 1193 fulfilled for listening, when the Local Endpoint (or Remote Endpoint, 1194 if specified) cannot be resolved, or when the application is 1195 prohibited from listening by policy. 1197 Preconnection -> Stopped<> 1199 A Stopped event occurs after the Preconnection has stopped listening. 1201 6.3. Peer-to-Peer Establishment: Rendezvous 1203 Simultaneous peer-to-peer Connection establishment is supported by 1204 the Rendezvous() Action: 1206 Preconnection.Rendezvous() 1208 The Preconnection Object must be specified with both a Local Endpoint 1209 and a Remote Endpoint, and also the transport properties and security 1210 parameters needed for Protocol Stack selection. 1212 The Rendezvous() Action causes the Preconnection to listen on the 1213 Local Endpoint for an incoming Connection from the Remote Endpoint, 1214 while simultaneously trying to establish a Connection from the Local 1215 Endpoint to the Remote Endpoint. This corresponds to a TCP 1216 simultaneous open, for example. 1218 The Rendezvous() Action consumes the Preconnection. Once 1219 Rendezvous() has been called, no further properties may be added to 1220 the Preconnection, and no subsequent establishment call may be made 1221 on the Preconnection. 1223 Preconnection -> RendezvousDone 1225 The RendezvousDone<> Event occurs when a Connection is established 1226 with the Remote Endpoint. For Connection-oriented transports, this 1227 occurs when the transport-layer connection is established; for 1228 Connectionless transports, it occurs when the first Message is 1229 received from the Remote Endpoint. The resulting Connection is 1230 contained within the RendezvousDone<> Event, and is ready to use as 1231 soon as it is passed to the application via the Event. 1233 Preconnection -> RendezvousError 1235 An RendezvousError occurs either when the Preconnection cannot be 1236 fulfilled for listening, when the Local Endpoint or Remote Endpoint 1237 cannot be resolved, when no transport-layer connection can be 1238 established to the Remote Endpoint, or when the application is 1239 prohibited from rendezvous by policy. 1241 When using some NAT traversal protocols, e.g., Interactive 1242 Connectivity Establishment (ICE) [RFC5245], it is expected that the 1243 Local Endpoint will be configured with some method of discovering NAT 1244 bindings, e.g., a Session Traversal Utilities for NAT (STUN) server. 1245 In this case, the Local Endpoint may resolve to a mixture of local 1246 and server reflexive addresses. The Resolve() action on the 1247 Preconnection can be used to discover these bindings: 1249 []Preconnection := Preconnection.Resolve() 1251 The Resolve() call returns a list of Preconnection Objects, that 1252 represent the concrete addresses, local and server reflexive, on 1253 which a Rendezvous() for the Preconnection will listen for incoming 1254 Connections. These resolved Preconnections will share all other 1255 Properties with the Preconnection from which they are derived, though 1256 some Properties may be made more-specific by the resolution process. 1257 This list can be passed to a peer via a signalling protocol, such as 1258 SIP [RFC3261] or WebRTC [RFC7478], to configure the remote. 1260 6.4. Connection Groups 1262 Groups of Connections can be created using the Clone Action: 1264 Connection := Connection.Clone() 1266 Calling Clone on a Connection yields a group of two Connections: the 1267 parent Connection on which Clone was called, and the resulting cloned 1268 Connection. These connections are "entangled" with each other, and 1269 become part of a Connection Group. Calling Clone on any of these two 1270 Connections adds a third Connection to the Connection Group, and so 1271 on. Connections in a Connection Group share all Protocol Properties 1272 that are not applicable to a Message. 1274 Changing one of these Protocol Properties on one Connection in the 1275 group changes it for all others. Per-Message Protocol Properties, 1276 however, are not entangled. For example, changing "Timeout for 1277 aborting Connection" (see Section 9.1.4) on one Connection in a group 1278 will automatically change this Protocol Property for all Connections 1279 in the group in the same way. However, changing "Lifetime" (see 1280 Section 7.3.1) of a Message will only affect a single Message on a 1281 single Connection, entangled or not. 1283 If the underlying protocol supports multi-streaming, it is natural to 1284 use this functionality to implement Clone. In that case, entangled 1285 Connections are multiplexed together, giving them similar treatment 1286 not only inside endpoints but also across the end-to-end Internet 1287 path. 1289 If the underlying Protocol Stack does not support cloning, or cannot 1290 create a new stream on the given Connection, then attempts to clone a 1291 connection will result in a CloneError: 1293 Connection -> CloneError<> 1295 The Protocol Property "Priority" operates on entangled Connections as 1296 in Section 7.3.2: when allocating available network capacity among 1297 Connections in a Connection Group, sends on Connections with higher 1298 Priority values will be prioritized over sends on Connections with 1299 lower Priority values. An ideal transport system implementation 1300 would assign each Connection the capacity share (M-N) x C / M, where 1301 N is the Connection's Priority value, M is the maximum Priority value 1302 used by all Connections in the group and C is the total available 1303 capacity. However, the Priority setting is purely advisory, and no 1304 guarantees are given about the way capacity is shared. Each 1305 implementation is free to implement a way to share capacity that it 1306 sees fit. 1308 7. Sending Data 1310 Once a Connection has been established, it can be used for sending 1311 data. Data is sent in terms of Messages, which allow the application 1312 to communicate the boundaries of the data being transferred. By 1313 default, Send enqueues a complete Message, and takes optional per- 1314 Message properties (see Section 7.1). All Send actions are 1315 asynchronous, and deliver events (see Section 7.2). Sending partial 1316 Messages for streaming large data is also supported (see 1317 Section 7.4). 1319 Messages are sent on a Connection using the Send action: 1321 Connection.Send(messageData, messageContext?, endOfMessage?) 1323 where messageData is the data object to send. The optional 1324 messageContext parameter supports per-message properties and is 1325 described in Section 7.3. The optional endOfMessage parameter 1326 supports partial sending and is described in Section 7.4. 1328 7.1. Basic Sending 1330 The most basic form of sending on a connection involves enqueuing a 1331 single Data block as a complete Message, with default Message 1332 Properties. Message data is created as an array of octets, and the 1333 resulting object contains both the byte array and the length of the 1334 array. 1336 messageData := "hello".octets() 1337 Connection.Send(messageData) 1339 The interpretation of a Message to be sent is dependent on the 1340 implementation, and on the constraints on the Protocol Stacks implied 1341 by the Connection's transport properties. For example, a Message may 1342 be a single datagram for UDP Connections; or an HTTP Request for HTTP 1343 Connections. 1345 Some transport protocols can deliver arbitrarily sized Messages, but 1346 other protocols constrain the maximum Message size. Applications can 1347 query the protocol property Maximum Message Size on Send to determine 1348 the maximum size allowed for a single Message. If a Message is too 1349 large to fit in the Maximum Message Size for the Connection, the Send 1350 will fail with a SendError event (Section 7.2.3). For example, it is 1351 invalid to send a Message over a UDP connection that is larger than 1352 the available datagram sending size. 1354 7.2. Send Events 1356 Like all Actions in this interface, the Send Action is asynchronous. 1357 There are several events that can be delivered in response to Sending 1358 a Message. 1360 Note that if partial Sends are used (Section 7.4), there will still 1361 be exactly one Send Event delivered for each call to Send. For 1362 example, if a Message expired while two requests to Send data for 1363 that Message are outstanding, there will be two Expired events 1364 delivered. 1366 7.2.1. Sent 1368 Connection -> Sent 1370 The Sent Event occurs when a previous Send Action has completed, 1371 i.e., when the data derived from the Message has been passed down or 1372 through the underlying Protocol Stack and is no longer the 1373 responsibility of the implementation of this interface. The exact 1374 disposition of the Message (i.e., whether it has actually been 1375 transmitted, moved into a buffer on the network interface, moved into 1376 a kernel buffer, and so on) when the Sent Event occurs is 1377 implementation-specific. The Sent Event contains an implementation- 1378 specific reference to the Message to which it applies. 1380 Sent Events allow an application to obtain an understanding of the 1381 amount of buffering it creates. That is, if an application calls the 1382 Send Action multiple times without waiting for a Sent Event, it has 1383 created more buffer inside the transport system than an application 1384 that always waits for the Sent Event before calling the next Send 1385 Action. 1387 7.2.2. Expired 1389 Connection -> Expired 1391 The Expired Event occurs when a previous Send Action expired before 1392 completion; i.e. when the Message was not sent before its Lifetime 1393 (see Section 7.3.1) expired. This is separate from SendError, as it 1394 is an expected behavior for partially reliable transports. The 1395 Expired Event contains an implementation-specific reference to the 1396 Message to which it applies. 1398 7.2.3. SendError 1400 Connection -> SendError 1402 A SendError occurs when a Message could not be sent due to an error 1403 condition: an attempt to send a Message which is too large for the 1404 system and Protocol Stack to handle, some failure of the underlying 1405 Protocol Stack, or a set of Message Properties not consistent with 1406 the Connection's transport properties. The SendError contains an 1407 implementation-specific reference to the Message to which it applies. 1409 7.3. Message Properties 1411 Applications may need to annotate the Messages they send with extra 1412 information to control how data is scheduled and processed by the 1413 transport protocols in the Connection. A MessageContext object 1414 contains properties for sending Messages, and can be passed to the 1415 Send Action. Note that these properties are per-Message, not per- 1416 Send if partial Messages are sent (Section 7.4). All data blocks 1417 associated with a single Message share properties. For example, it 1418 would not make sense to have the beginning of a Message expire, but 1419 allow the end of a Message to still be sent. 1421 messageData := "hello".octets() 1422 messageContext := NewMessageContext() 1423 messageContext.add(parameter, value) 1424 Connection.Send(messageData, messageContext) 1426 The simpler form of Send that does not take any messageContext is 1427 equivalent to passing a default MessageContext with not values added. 1429 If an application wants to override Message Properties for a specific 1430 message, it can acquire an empty MessageContext Object and add all 1431 desired Message Properties to that Object. It can then reuse the 1432 same messageContext Object for sending multiple Messages with the 1433 same properties. 1435 Properties may be added to a MessageContext object only before the 1436 context is used for sending. Once a messageContext has been used 1437 with a Send call, modifying any of its properties is invalid. 1439 Message Properties may be inconsistent with the properties of the 1440 Protocol Stacks underlying the Connection on which a given Message is 1441 sent. For example, a Connection must provide reliability to allow 1442 setting an infinitie value for the lifetime property of a Message. 1443 Sending a Message with Message Properties inconsistent with the 1444 Selection Properties of the Connection yields an error. 1446 The following Message Properties are supported: 1448 7.3.1. Lifetime 1450 Name: msg-lifetime 1452 Type: Integer 1454 Lifetime specifies how long a particular Message can wait to be sent 1455 to the remote endpoint before it is irrelevant and no longer needs to 1456 be (re-)transmitted. This is a hint to the transport system - it is 1457 not guaranteed that a Message will not be sent when its Lifetime has 1458 expired. 1460 Setting a Message's Lifetime to infinite indicates that the 1461 application does not wish to apply a time constraint on the 1462 transmission of the Message, but it does not express a need for 1463 reliable delivery; reliability is adjustable per Message via the 1464 "Reliable Data Transfer (Message)" property (see Section 7.3.7). The 1465 type and units of Lifetime are implementation-specific. 1467 7.3.2. Priority 1469 Name: msg-prio 1471 Type: Integer (non-negative) 1473 This property represents a hierarchy of priorities. It can specify 1474 the priority of a Message, relative to other Messages sent over the 1475 same Connection. 1477 A Message with Priority 0 will yield to a Message with Priority 1, 1478 which will yield to a Message with Priority 2, and so on. Priorities 1479 may be used as a sender-side scheduling construct only, or be used to 1480 specify priorities on the wire for Protocol Stacks supporting 1481 prioritization. 1483 Note that this property is not a per-message override of the 1484 connection Priority - see Section 9.1.3. Both Priority properties 1485 may interact, but can be used independently and be realized by 1486 different mechanisms. 1488 7.3.3. Ordered 1490 Name: msg-ordered 1492 Type: Boolean 1494 If true, it specifies that the receiver-side transport protocol stack 1495 only deliver the Message to the receiving application after the 1496 previous ordered Message which was passed to the same Connection via 1497 the Send Action, when such a Message exists. If false, the Message 1498 may be delivered to the receiving application out of order. This 1499 property is used for protocols that support preservation of data 1500 ordering, see Section 5.2.4, but allow out-of-order delivery for 1501 certain messages. 1503 7.3.4. Idempotent 1505 Name: idempotent 1507 Type: Boolean 1509 If true, it specifies that a Message is safe to send to the remote 1510 endpoint more than once for a single Send Action. It is used to mark 1511 data safe for certain 0-RTT establishment techniques, where 1512 retransmission of the 0-RTT data may cause the remote application to 1513 receive the Message multiple times. 1515 7.3.5. Final 1517 Type: Boolean 1519 Name: final 1521 If true, this Message is the last one that the application will send 1522 on a Connection. This allows underlying protocols to indicate to the 1523 Remote Endpoint that the Connection has been effectively closed in 1524 the sending direction. For example, TCP-based Connections can send a 1525 FIN once a Message marked as Final has been completely sent, 1526 indicated by marking endOfMessage. Protocols that do not support 1527 signalling the end of a Connection in a given direction will ignore 1528 this property. 1530 Note that a Final Message must always be sorted to the end of a list 1531 of Messages. The Final property overrides Priority and any other 1532 property that would re-order Messages. If another Message is sent 1533 after a Message marked as Final has already been sent on a 1534 Connection, the Send Action for the new Message will cause a 1535 SendError Event. 1537 7.3.6. Corruption Protection Length 1539 Name: msg-checksum-len 1541 Type: Integer (non-negative with -1 as special value) 1543 This property specifies the length of the section of the Message, 1544 starting from byte 0, that the application requires to be delivered 1545 without corruption due to lower layer errors. It is used to specify 1546 options for simple integrity protection via checksums. By default, 1547 the entire Message is protected by a checksum. A value of 0 means 1548 that no checksum is required, and a special value (e.g. -1) can be 1549 used to indicate the default. Only full coverage is guaranteed, any 1550 other requests are advisory. 1552 7.3.7. Reliable Data Transfer (Message) 1554 Name: msg-reliable 1556 Type: Boolean 1558 When true, this property specifies that a message should be sent in 1559 such a way that the transport protocol ensures all data is received 1560 on the other side without corruption. Changing the 'Reliable Data 1561 Transfer' property on Messages is only possible for Connections that 1562 were established with the Selection Property 'Reliable Data Transfer 1563 (Connection)' enabled. When this is not the case, changing it will 1564 generate an error. Disabling this property indicates that the 1565 transport system may disable retransmissions or other reliability 1566 mechanisms for this particular Message, but such disabling is not 1567 guaranteed. 1569 7.3.8. Message Capacity Profile Override 1571 Name: msg-capacity-profile 1573 Type: Enumeration 1575 This enumerated property specifies the application's preferred 1576 tradeoffs for sending this Message; it is a per-Message override of 1577 the Capacity Profile protocol and path selection property (see 1578 Section 9.1.10). 1580 The following values are valid for Transmission Profile: 1582 Default: No special optimizations of the tradeoff between delay, 1583 delay variation, and bandwidth efficiency should be made when 1584 sending this message. 1586 Low Latency: Response time (latency) should be optimized at the 1587 expense of efficiently using the available capacity when sending 1588 this message. This can be used by the system to disable the 1589 coalescing of multiple small Messages into larger packets (Nagle's 1590 algorithm); to prefer immediate acknowledgment from the peer 1591 endpoint when supported by the underlying transport; to signal a 1592 preference for lower-latency, higher-loss treatment; and so on. 1594 [TODO: This is inconsistent with {prop-cap-profile}} - needs to be 1595 fixed] 1597 7.3.9. Singular Transmission 1599 Name: singular-transmission 1601 Type: Boolean 1603 This property specifies that a message should be sent and received as 1604 a single packet without transport-layer segmentation or network-layer 1605 fragmentation. Attempts to send a message with this property set 1606 with a size greater to the transport's current estimate of its 1607 maximum transmission segment size will result in a "SendError". When 1608 used with transports supporting this functionality and running over 1609 IP version 4, the Don't Fragment bit will be set. 1611 7.4. Partial Sends 1613 It is not always possible for an application to send all data 1614 associated with a Message in a single Send Action. The Message data 1615 may be too large for the application to hold in memory at one time, 1616 or the length of the Message may be unknown or unbounded. 1618 Partial Message sending is supported by passing an endOfMessage 1619 boolean parameter to the Send Action. This value is always true by 1620 default, and the simpler forms of Send are equivalent to passing true 1621 for endOfMessage. 1623 The following example sends a Message in two separate calls to Send. 1625 messageContext := NewMessageContext() 1626 messageContext.add(parameter, value) 1628 messageData := "hel".octets() 1629 endOfMessage := false 1630 Connection.Send(messageData, messageContext, endOfMessage) 1632 messageData := "lo".octets() 1633 endOfMessage := true 1634 Connection.Send(messageData, messageContext, endOfMessage) 1636 All data sent with the same MessageContext object will be treated as 1637 belonging to the same Message, and will constitute an in-order series 1638 until the endOfMessage is marked. Once the end of the Message is 1639 marked, the MessageContext object may be re-used as a new Message 1640 with identical parameters. 1642 7.5. Batching Sends 1644 In order to reduce the overhead of sending multiple small Messages on 1645 a Connection, the application may want to batch several Send actions 1646 together. This provides a hint to the system that the sending of 1647 these Messages should be coalesced when possible, and that sending 1648 any of the batched Messages may be delayed until the last Message in 1649 the batch is enqueued. 1651 Connection.Batch( 1652 Connection.Send(messageData) 1653 Connection.Send(messageData) 1654 ) 1656 7.6. Send on Active Open: InitiateWithSend 1658 For application-layer protocols where the Connection initiator also 1659 sends the first message, the InitiateWithSend() action combines 1660 Connection initiation with a first Message sent: 1662 Connection := Preconnection.InitiateWithSend(messageData, messageContext?, timeout?) 1664 Whenever possible, a messageContext should be provided to declare the 1665 message passed to InitiateWithSend as idempotent. This allows the 1666 transport system to make use of 0-RTT establishment in case this is 1667 supported by the available protocol stacks. When the selected 1668 stack(s) do not support transmitting data upon connection 1669 establishment, InitiateWithSend is identical to Initiate() followed 1670 by Send(). 1672 Neither partial sends nor send batching are supported by 1673 InitiateWithSend(). 1675 The Events that may be sent after InitiateWithSend() are equivalent 1676 to those that would be sent by an invocation of Initate() followed 1677 immediately by an invocation of Send(), with the caveat that a send 1678 failure that occurs because the Connection could not be established 1679 will not result in a SendError separate from the InitiateError 1680 signaling the failure of Connection establishment. 1682 7.7. Sender-side Framing 1684 Sender-side framing allows a caller to provide the interface with a 1685 function that takes a Message of an appropriate application-layer 1686 type and returns an array of octets, the on-the-wire representation 1687 of the Message to be handed down to the Protocol Stack. It consists 1688 of a Framer Object with a single Action, Frame. Since the Framer 1689 depends on the protocol used at the application layer, it is bound to 1690 the Preconnection during the pre-establishment phase: 1692 Preconnection.FrameWith(Framer) 1694 OctetArray := Framer.Frame(messageData) 1696 Sender-side framing is a convenience feature of the interface, for 1697 parity with receiver-side framing (see Section 8.4). 1699 8. Receiving Data 1701 Once a Connection is established, it can be used for receiving data. 1702 As with sending, data is received in terms of Messages. Receiving is 1703 an asynchronous operation, in which each call to Receive enqueues a 1704 request to receive new data from the connection. Once data has been 1705 received, or an error is encountered, an event will be delivered to 1706 complete the Receive request (see Section 8.2). 1708 As with sending, the type of the Message to be passed is dependent on 1709 the implementation, and on the constraints on the Protocol Stacks 1710 implied by the Connection's transport parameters. 1712 8.1. Enqueuing Receives 1714 Receive takes two parameters to specify the length of data that an 1715 application is willing to receive, both of which are optional and 1716 have default values if not specified. 1718 Connection.Receive(minIncompleteLength?, maxLength?) 1719 By default, Receive will try to deliver complete Messages in a single 1720 event (Section 8.2.1). 1722 The application can set a minIncompleteLength value to indicates the 1723 smallest partial Message data size in bytes that should be delivered 1724 in response to this Receive. By default, this value is infinite, 1725 which means that only complete Messages should be delivered (see 1726 Section 8.2.2 and Section 8.4 for more information on how this is 1727 accomplished). If this value is set to some smaller value, the 1728 associated receive event will be triggered only when at least that 1729 many bytes are available, or the Message is complete with fewer 1730 bytes, or the system needs to free up memory. Applications should 1731 always check the length of the data delivered to the receive event 1732 and not assume it will be as long as minIncompleteLength in the case 1733 of shorter complete Messages or memory issues. 1735 The maxLength argument indicates the maximum size of a Message in 1736 bytes the application is currently prepared to receive. The default 1737 value for maxLength is infinite. If an incoming Message is larger 1738 than the minimum of this size and the maximum Message size on receive 1739 for the Connection's Protocol Stack, it will be delivered via 1740 ReceivedPartial events (Section 8.2.2). 1742 Note that maxLength does not guarantee that the application will 1743 receive that many bytes if they are available; the interface may 1744 return ReceivedPartial events with less data than maxLength according 1745 to implementation constraints. 1747 8.2. Receive Events 1749 Each call to Receive will be paired with a single Receive Event, 1750 which can be a success or an error. This allows an application to 1751 provide backpressure to the transport stack when it is temporarily 1752 not ready to receive messages. 1754 8.2.1. Received 1756 Connection -> Received 1758 A Received event indicates the delivery of a complete Message. It 1759 contains two objects, the received bytes as messageData, and the 1760 metadata and properties of the received Message as messageContext. 1761 See Section 8.3 for details about the received context. 1763 The messageData object provides access to the bytes that were 1764 received for this Message, along with the length of the byte array. 1766 See Section 8.4 for handling Message framing in situations where the 1767 Protocol Stack provides octet-stream transport only. 1769 8.2.2. ReceivedPartial 1771 Connection -> ReceivedPartial 1773 If a complete Message cannot be delivered in one event, one part of 1774 the Message may be delivered with a ReceivedPartial event. In order 1775 to continue to receive more of the same Message, the application must 1776 invoke Receive again. 1778 Multiple invocations of ReceivedPartial deliver data for the same 1779 Message by passing the same MessageContext, until the endOfMessage 1780 flag is delivered or a ReceiveError occurs. All partial blocks of a 1781 single Message are delivered in order without gaps. This event does 1782 not support delivering discontiguous partial Messages. 1784 If the minIncompleteLength in the Receive request was set to be 1785 infinite (indicating a request to receive only complete Messages), 1786 the ReceivedPartial event may still be delivered if one of the 1787 following conditions is true: 1789 o the underlying Protocol Stack supports message boundary 1790 preservation, and the size of the Message is larger than the 1791 buffers available for a single message; 1793 o the underlying Protocol Stack does not support message boundary 1794 preservation, and the deframer (see Section 8.4) cannot determine 1795 the end of the message using the buffer space it has available; or 1797 o the underlying Protocol Stack does not support message boundary 1798 preservation, and no deframer was supplied by the application 1800 Note that in the absence of message boundary preservation or 1801 deframing, all bytes received on the Connection will be represented 1802 as one large message of indeterminate length. 1804 8.2.3. ReceiveError 1806 Connection -> ReceiveError 1808 A ReceiveError occurs when data is received by the underlying 1809 Protocol Stack that cannot be fully retrieved or deframed, or when 1810 some other indication is received that reception has failed. Such 1811 conditions that irrevocably lead to the termination of the Connection 1812 are signaled using ConnectionError instead (see Section 10). 1814 The ReceiveError event passes an optional associated MessageContext. 1815 This may indicate that a Message that was being partially received 1816 previously, but had not completed, encountered an error and will not 1817 be completed. 1819 8.3. Message Receive Context 1821 Each Received Message Context may contain metadata from protocols in 1822 the Protocol Stack; which metadata is available is Protocol Stack 1823 dependent. The following metadata values are supported: 1825 8.3.1. ECN 1827 When available, Message metadata carries the value of the Explicit 1828 Congestion Notification (ECN) field. This information can be used 1829 for logging and debugging purposes, and for building applications 1830 which need access to information about the transport internals for 1831 their own operation. 1833 8.3.2. Early Data 1835 In some cases it may be valuable to know whether data was read as 1836 part of early data transfer (before connection establishment has 1837 finished). This is useful if applications need to treat early data 1838 separately, e.g., if early data has different security properties 1839 than data sent after connection establishment. In the case of TLS 1840 1.3, client early data can be replayed maliciously (see [RFC8446]). 1841 Thus, receivers may wish to perform additional checks for early data 1842 to ensure it is idempotent or not replayed. If TLS 1.3 is available 1843 and the recipient Message was sent as part of early data, the 1844 corresponding metadata carries a flag indicating as such. If early 1845 data is enabled, applications should check this metadata field for 1846 Messages received during connection establishment and respond 1847 accordingly. 1849 8.3.3. Receiving Final Messages 1851 The Received Message Context can indicate whether or not this Message 1852 is the Final Message on a Connection. For any Message that is marked 1853 as Final, the application can assume that there will be no more 1854 Messages received on the Connection once the Message has been 1855 completely delivered. This corresponds to the Final property that 1856 may be marked on a sent Message Section 7.3.5. 1858 Some transport protocols and peers may not support signaling of the 1859 Final property. Applications therefore should not rely on receiving 1860 a Message marked Final to know that the other endpoint is done 1861 sending on a connection. 1863 Any calls to Receive once the Final Message has been delivered will 1864 result in errors. 1866 8.4. Receiver-side De-framing over Stream Protocols 1868 The Receive Event is intended to be fired once per application-layer 1869 Message sent by the remote endpoint; i.e., it is a desired property 1870 of this interface that a Send at one end of a Connection maps to 1871 exactly one Receive on the other end. This is possible with Protocol 1872 Stacks that provide message boundary preservation, but is not the 1873 case over Protocol Stacks that provide a simple octet stream 1874 transport. 1876 For preserving message boundaries over stream transports, this 1877 interface provides receiver-side de-framing. This facility is based 1878 on the observation that, since many of our current application 1879 protocols evolved over TCP, which does not provide message boundary 1880 preservation, and since many of these protocols require message 1881 boundaries to function, each application layer protocol has defined 1882 its own framing. A Deframer allows an application to push this de- 1883 framing down into the interface, in order to transform an octet 1884 stream into a sequence of Messages. 1886 Concretely, receiver-side de-framing allows a caller to provide the 1887 interface with a function that takes an octet stream, as provided by 1888 the underlying Protocol Stack, reads and returns a single Message of 1889 an appropriate type for the application and platform, and leaves the 1890 octet stream at the start of the next Message to deframe. It 1891 consists of a Deframer Object with a single Action, Deframe. Since 1892 the Deframer depends on the protocol used at the application layer, 1893 it is bound to the Preconnection during the pre-establishment phase: 1895 Preconnection.DeframeWith(Deframer) 1897 {messageData} := Deframer.Deframe(OctetStream) 1899 9. Managing Connections 1901 During pre-establishment and after establishment, connections can be 1902 configured and queried using Connection Properties, and asynchronous 1903 information may be available about the state of the connection via 1904 Soft Errors. 1906 Connection Properties represent the configuration and state of the 1907 selected Protocol Stack(s) backing a Connection. These Connection 1908 Properties may be Generic, applying regardless of transport protocol, 1909 or Specific, applicable to a single implementation of a single 1910 transport protocol stack. Generic Connection Properties are defined 1911 in Section 9.1 below. Specific Protocol Properties are defined in a 1912 transport- and implementation-specific way, and must not be assumed 1913 to apply across different protocols. Attempts to set Specific 1914 Protocol Properties on a protocol stack not containing that specific 1915 protocol are simply ignored, and do not raise an error; however, too 1916 much reliance by an application on Specific Protocol Properties may 1917 significantly reduce the flexibility of a transport services 1918 implementation. 1920 The application can set and query Connection Properties on a per- 1921 Connection basis. Connection Properties that are not read-only can 1922 be set during pre-establishment (see Section 5.2), as well as on 1923 connections directly using the SetProperty action: 1925 Connection.SetProperty(property, value) 1927 At any point, the application can query Connection Properties. 1929 ConnectionProperties := Connection.GetProperties() 1931 Depending on the status of the connection, the queried Connection 1932 Properties will include different information: 1934 o The connection state, which can be one of the following: 1935 Establishing, Established, Closing, or Closed. 1937 o Whether the connection can be used to send data. A connection can 1938 not be used for sending if the connection was created with the 1939 Selection Property "Direction of Communication" set to 1940 "unidirectional receive" or if a Message marked as "Final" was 1941 sent over this connection, see Section 7.3.5. 1943 o Whether the connection can be used to receive data. A connection 1944 can not be used for reading if the connection was created with the 1945 Selection Property "Direction of Communication" set to 1946 "unidirectional send" or if a Message marked as "Final" was 1947 received, see Section 8.3.3. The latter is only supported by 1948 certain transport protocols, e.g., by TCP as half-closed 1949 connection. 1951 o For Connections that are Establishing: Transport Properties that 1952 the application specified on the Preconnection, see Section 5.2. 1954 o For Connections that are Established, Closing, or Closed: 1955 Selection (Section 5.2) and Connection Properties (Section 9.1) of 1956 the actual protocols that were selected and instantiated. 1957 Selection Properties indicate whether or not the Connection has or 1958 offers a certain Selection Property. Note that the actually 1959 instantiated protocol stack may not match all Protocol Selection 1960 Properties that the application specified on the Preconnection. 1961 For example, a certain Protocol Selection Property that an 1962 application specified as Preferred may not actually be present in 1963 the chosen protocol stack because none of the currently available 1964 transport protocols had this feature. 1966 o For Connections that are Established, additional properties of the 1967 path(s) in use. These properties can be derived from the local 1968 provisioning domain [RFC7556], measurements by the Protocol Stack, 1969 or other sources. 1971 9.1. Generic Connection Properties 1973 The Connection Properties defined as independent, and available on 1974 all Connections are defined in the subsections below. 1976 Note that many protocol properties have a corresponding selection 1977 property, which prefers protocols providing a specific transport 1978 feature that controlled by that protocol property. [EDITOR'S NOTE: 1979 todo: add these cross-references up to Section 5.2] 1981 9.1.1. Retransmission threshold before excessive retransmission 1982 notification 1984 Name: retransmit-notify-threshold 1986 Type: Integer 1988 This property specifies after how many retransmissions to inform the 1989 application about "Excessive Retransmissions". 1991 9.1.2. Required minimum coverage of the Corruption Protection for 1992 receiving 1994 Name: recv-checksum-len 1996 Type: Integer 1998 This property specifies the part of the received data that needs to 1999 be covered by a checksum. It is given in Bytes. A value of 0 means 2000 that no checksum is required, and a special value (e.g., -1) 2001 indicates full checksum coverage. 2003 9.1.3. Priority (Connection) 2005 Name: conn-prio 2007 Type: Integer 2009 This Property is a non-negative integer representing the relative 2010 inverse priority of this Connection relative to other Connections in 2011 the same Connection Group. It has no effect on Connections not part 2012 of a Connection Group. As noted in Section 6.4, this property is not 2013 entangled when Connections are cloned. 2015 9.1.4. Timeout for aborting Connection 2017 Name: conn-timeout 2019 Type: Numeric 2021 This property specifies how long to wait before deciding that a 2022 Connection has failed when trying to reliably deliver data to the 2023 destination. Adjusting this Property will only take effect when the 2024 underlying stack supports reliability. 2026 9.1.5. Connection group transmission scheduler 2028 Name: conn-scheduler 2030 Type: Enumeration 2032 This property specifies which scheduler should be used among 2033 Connections within a Connection Group, see Section 6.4. The set of 2034 schedulers can be taken from [I-D.ietf-tsvwg-sctp-ndata]. 2036 9.1.6. Maximum message size concurrent with Connection establishment 2038 Name: zero-rtt-msg-max-len 2040 Type: Integer (read only) 2042 This property represents the maximum Message size that can be sent 2043 before or during Connection establishment, see also Section 7.3.4. 2044 It is given in Bytes. 2046 9.1.7. Maximum Message size before fragmentation or segmentation 2048 Name: singular-transmission-msg-max-len 2050 Type: Integer (read only) 2051 This property, if applicable, represents the maximum Message size 2052 that can be sent without incurring network-layer fragmentation or 2053 transport layer segmentation at the sender. 2055 9.1.8. Maximum Message size on send 2057 Name: send-msg-max-len 2059 Type: Integer (read only) 2061 This property represents the maximum Message size that can be sent. 2063 9.1.9. Maximum Message size on receive 2065 Name: recv-msg-max-len 2067 Type: Integer (read only) 2069 This numeric property represents the maximum Message size that can be 2070 received. 2072 9.1.10. Capacity Profile 2074 Name: conn-capacity-profile 2076 This property specifies the desired network treatment for traffic 2077 sent by the application and the tradeoffs the application is prepared 2078 to make in path and protocol selection to receive that desired 2079 treatment. When the capacity profile is set to a value other than 2080 Default, the transport system should select paths and profiles to 2081 optimize for the capacity profile specified. The following values 2082 are valid for the Capacity Profile: 2084 Default: The application makes no representation about its expected 2085 capacity profile. No special optimizations of the tradeoff 2086 between delay, delay variation, and bandwidth efficiency should be 2087 made when selecting and configuring transport protocol stacks. 2088 Transport system implementations that map the requested capacity 2089 profile onto per-connection DSCP signaling without multiplexing 2090 SHOULD assign the DSCP Default Forwarding [RFC2474] PHB; when the 2091 Connection is multiplexed, the guidelines in section 6 of 2092 [RFC7657] apply. 2094 Scavenger: The application is not interactive. It expects to send 2095 and/or receive data without any urgency. This can, for example, 2096 be used to select protocol stacks with scavenger transmission 2097 control and/or to assign the traffic to a lower-effort service. 2098 Transport system implementations that map the requested capacity 2099 profile onto per-connection DSCP signaling without multiplexing 2100 SHOULD assign the DSCP Less than Best Effort [LE-PHB] PHB; when 2101 the Connection is multiplexed, the guidelines in section 6 of 2102 [RFC7657] apply. 2104 Low Latency/Interactive: The application is interactive, and prefers 2105 loss to latency. Response time should be optimized at the expense 2106 of bandwidth efficiency and delay variation when sending on this 2107 connection. This can be used by the system to disable the 2108 coalescing of multiple small Messages into larger packets (Nagle's 2109 algorithm); to prefer immediate acknowledgment from the peer 2110 endpoint when supported by the underlying transport; and so on. 2111 Transport system implementations that map the requested capacity 2112 profile onto per-connection DSCP signaling without multiplexing 2113 SHOULD assign the DSCP Expedited Forwarding [RFC3246] PHB; when 2114 the Connection is multiplexed, the guidelines in section 6 of 2115 [RFC7657] apply. 2117 Low Latency/Non-Interactive: The application prefers loss to latency 2118 but is not interactive. Response time should be optimized at the 2119 expense of bandwidth efficiency and delay variation when sending 2120 on this connection.Transport system implementations that map the 2121 requested capacity profile onto per-connection DSCP signaling 2122 without multiplexing SHOULD assign a DSCP Assured Forwarding 2123 (AF21,AF22,AF23,AF24) [RFC2597] PHB; when the Connection is 2124 multiplexed, the guidelines in section 6 of [RFC7657] apply. 2126 Constant-Rate Streaming: The application expects to send/receive 2127 data at a constant rate after Connection establishment. Delay and 2128 delay variation should be minimized at the expense of bandwidth 2129 efficiency. This implies that the Connection may fail if the 2130 desired rate cannot be maintained across the Path. A transport 2131 may interpret this capacity profile as preferring a circuit 2132 breaker [RFC8084] to a rate-adaptive congestion controller. 2133 Transport system implementations that map the requested capacity 2134 profile onto per-connection DSCP signaling without multiplexing 2135 SHOULD assign a DSCP Assured Forwarding (AF31,AF32,AF33,AF34) 2136 [RFC2597] PHB; when the Connection is multiplexed, the guidelines 2137 in section 6 of [RFC7657] apply. 2139 High Throughput Data: The application expects to send/receive data 2140 at the maximum rate allowed by its congestion controller over a 2141 relatively long period of time. Transport system implementations 2142 that map the requested capacity profile onto per-connection DSCP 2143 signaling without multiplexing SHOULD assign a DSCP Assured 2144 Forwarding (AF11,AF12,AF13,AF14) [RFC2597] PHB per section 4.8 of 2145 [RFC4594]. When the Connection is multiplexed, the guidelines in 2146 section 6 of [RFC7657] apply. 2148 The Capacity Profile for a selected protocol stack may be modified on 2149 a per-Message basis using the Transmission Profile Message Property; 2150 see Section 7.3.8. 2152 9.1.11. Bounds on Send or Receive Rate 2154 Name: max-send-rate / max-recv-rate 2156 Type: Integer (positive) 2158 This property specifies an upper-bound rate that a transfer is not 2159 expected to exceed (even if flow control and congestion control allow 2160 higher rates), and/or a lower-bound rate below which the application 2161 does not deem a data transfer useful. It is given in bits per 2162 second. 2164 9.1.12. TCP-specific Property: User Timeout 2166 This property specifies, for the case TCP becomes the chosen 2167 transport protocol: 2169 Advertised User Timeout (name: tcp.user-timeout-value, type: 2170 Integer): 2171 a time value to be advertised via the User Timeout Option (UTO) 2172 for the TCP at the remote endpoint to adapt its own "Timeout for 2173 aborting Connection" (see Section 9.1.4) value accordingly 2175 User Timeout Enabled (name: tcp.user-timeout, type: Boolean): a bool 2176 ean (default false) to control whether the UTO option is enabled 2177 for a connection. This applies to both sending and receiving. 2179 Changeable (name: tcp.user-timeout-recv, type: Boolean): a boolean 2180 (default true) which controls whether the "Timeout for aborting 2181 Connection" (see Section 9.1.4) may be changed based on a UTO 2182 option received from the remote peer. This boolean becomes false 2183 when "Timeout for aborting Connection" (see Section 9.1.4) is 2184 used. 2186 All of the above parameters are optional (e.g., it is possible to 2187 specify "User Timeout Enabled" as true, but not specify an Advertised 2188 User Timeout value; in this case, the TCP default will be used). 2190 9.2. Soft Errors 2192 Asynchronous introspection is also possible, via the SoftError Event. 2193 This event informs the application about the receipt of an ICMP error 2194 message related to the Connection. This will only happen if the 2195 underlying protocol stack supports access to soft errors; however, 2196 even if the underlying stack supports it, there is no guarantee that 2197 a soft error will be signaled. 2199 Connection -> SoftError<> 2201 9.3. Excessive retransmissions 2203 This event notifies the application of excessive retransmissions, 2204 based on a configured threshold (see Section 9.1.1). This will only 2205 happen if the underlying protocol stack supports reliability and, 2206 with it, such notifications. 2208 Connection -> ExcessiveRetransmission<> 2210 10. Connection Termination 2212 Close terminates a Connection after satisfying all the requirements 2213 that were specified regarding the delivery of Messages that the 2214 application has already given to the transport system. For example, 2215 if reliable delivery was requested for a Message handed over before 2216 calling Close, the transport system will ensure that this Message is 2217 indeed delivered. If the Remote Endpoint still has data to send, it 2218 cannot be received after this call. 2220 Connection.Close() 2222 The Closed Event can inform the application that the Remote Endpoint 2223 has closed the Connection; however, there is no guarantee that a 2224 remote Close will indeed be signaled. 2226 Connection -> Closed<> 2228 Abort terminates a Connection without delivering remaining data: 2230 Connection.Abort() 2232 A ConnectionError informs the application that data to could not be 2233 delivered after a timeout, or the other side has aborted the 2234 Connection; however, there is no guarantee that an Abort will indeed 2235 be signaled. 2237 Connection -> ConnectionError<> 2239 11. Connection State and Ordering of Operations and Events 2241 As this interface is designed to be independent of an 2242 implementation's concurrency model, the details of how exactly 2243 actions are handled, and on which threads/callbacks events are 2244 dispatched, are implementation dependent. 2246 Each transition of connection state is associated with one of more 2247 events: 2249 o Ready<> occurs when a Connection created with Initiate() or 2250 InitiateWithSend() transitions to Established state. 2252 o ConnectionReceived<> occurs when a Connection created with 2253 Listen() transitions to Established state. 2255 o RendezvousDone<> occurs when a Connection created with 2256 Rendezvous() transitions to Established state. 2258 o Closed<> occurs when a Connection transitions to Closed state 2259 without error. 2261 o InitiateError<> occurs when a Connection created with Initiate() 2262 transitions from Establishing state to Closed state due to an 2263 error. 2265 o ConnectionError<> occurs when a Connection transitions to Closed 2266 state due to an error in all other circumstances. 2268 The interface provides the following guarantees about the ordering of 2269 operations: 2271 o Sent<> events will occur on a Connection in the order in which the 2272 Messages were sent (i.e., delivered to the kernel or to the 2273 network interface, depending on implementation). 2275 o Received<> will never occur on a Connection before it is 2276 Established; i.e. before a Ready<> event on that Connection, or a 2277 ConnectionReceived<> or RendezvousDone<> containing that 2278 Connection. 2280 o No events will occur on a Connection after it is Closed; i.e., 2281 after a Closed<> event, an InitiateError<> or ConnectionError<> on 2282 that connection. To ensure this ordering, Closed<> will not occur 2283 on a Connection while other events on the Connection are still 2284 locally outstanding (i.e., known to the interface and waiting to 2285 be dealt with by the application). ConnectionError<> may occur 2286 after Closed<>, but the interface must gracefully handle all cases 2287 where application ignores these errors. 2289 12. IANA Considerations 2291 RFC-EDITOR: Please remove this section before publication. 2293 This document has no Actions for IANA. Later versions of this 2294 document may create IANA registries for generic transport property 2295 names and transport property namespaces (see Section 4.2.1). 2297 13. Security Considerations 2299 This document describes a generic API for interacting with a 2300 transport services (TAPS) system. Part of this API includes 2301 configuration details for transport security protocols, as discussed 2302 in Section 5.3. It does not recommend use (or disuse) of specific 2303 algorithms or protocols. Any API-compatible transport security 2304 protocol should work in a TAPS system. 2306 14. Acknowledgements 2308 This work has received funding from the European Union's Horizon 2020 2309 research and innovation programme under grant agreements No. 644334 2310 (NEAT) and No. 688421 (MAMI). 2312 This work has been supported by Leibniz Prize project funds of DFG - 2313 German Research Foundation: Gottfried Wilhelm Leibniz-Preis 2011 (FKZ 2314 FE 570/4-1). 2316 This work has been supported by the UK Engineering and Physical 2317 Sciences Research Council under grant EP/R04144X/1. 2319 Thanks to Stuart Cheshire, Josh Graessley, David Schinazi, and Eric 2320 Kinnear for their implementation and design efforts, including Happy 2321 Eyeballs, that heavily influenced this work. Thanks to Laurent Chuat 2322 and Jason Lee for initial work on the Post Sockets interface, from 2323 which this work has evolved. 2325 15. References 2327 15.1. Normative References 2329 [I-D.ietf-taps-arch] 2330 Pauly, T., Trammell, B., Brunstrom, A., Fairhurst, G., 2331 Perkins, C., Tiesel, P., and C. Wood, "An Architecture for 2332 Transport Services", draft-ietf-taps-arch-02 (work in 2333 progress), October 2018. 2335 [I-D.ietf-tsvwg-rtcweb-qos] 2336 Jones, P., Dhesikan, S., Jennings, C., and D. Druta, "DSCP 2337 Packet Markings for WebRTC QoS", draft-ietf-tsvwg-rtcweb- 2338 qos-18 (work in progress), August 2016. 2340 [I-D.ietf-tsvwg-sctp-ndata] 2341 Stewart, R., Tuexen, M., Loreto, S., and R. Seggelmann, 2342 "Stream Schedulers and User Message Interleaving for the 2343 Stream Control Transmission Protocol", draft-ietf-tsvwg- 2344 sctp-ndata-13 (work in progress), September 2017. 2346 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2347 Requirement Levels", BCP 14, RFC 2119, 2348 DOI 10.17487/RFC2119, March 1997, 2349 . 2351 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2352 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2353 May 2017, . 2355 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2356 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2357 . 2359 15.2. Informative References 2361 [I-D.ietf-taps-minset] 2362 Welzl, M. and S. Gjessing, "A Minimal Set of Transport 2363 Services for End Systems", draft-ietf-taps-minset-11 (work 2364 in progress), September 2018. 2366 [I-D.ietf-taps-transport-security] 2367 Wood, C., Enghardt, T., Pauly, T., Perkins, C., and K. 2368 Rose, "A Survey of Transport Security Protocols", draft- 2369 ietf-taps-transport-security-06 (work in progress), March 2370 2019. 2372 [LE-PHB] Bless, R., "A Lower Effort Per-Hop Behavior (LE PHB) for 2373 Differentiated Services", draft-ietf-tsvwg-le-phb-10 (work 2374 in progress), March 2019. 2376 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 2377 RFC 793, DOI 10.17487/RFC0793, September 1981, 2378 . 2380 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 2381 "Definition of the Differentiated Services Field (DS 2382 Field) in the IPv4 and IPv6 Headers", RFC 2474, 2383 DOI 10.17487/RFC2474, December 1998, 2384 . 2386 [RFC2597] Heinanen, J., Baker, F., Weiss, W., and J. Wroclawski, 2387 "Assured Forwarding PHB Group", RFC 2597, 2388 DOI 10.17487/RFC2597, June 1999, 2389 . 2391 [RFC2914] Floyd, S., "Congestion Control Principles", BCP 41, 2392 RFC 2914, DOI 10.17487/RFC2914, September 2000, 2393 . 2395 [RFC3246] Davie, B., Charny, A., Bennet, J., Benson, K., Le Boudec, 2396 J., Courtney, W., Davari, S., Firoiu, V., and D. 2397 Stiliadis, "An Expedited Forwarding PHB (Per-Hop 2398 Behavior)", RFC 3246, DOI 10.17487/RFC3246, March 2002, 2399 . 2401 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 2402 A., Peterson, J., Sparks, R., Handley, M., and E. 2403 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 2404 DOI 10.17487/RFC3261, June 2002, 2405 . 2407 [RFC4594] Babiarz, J., Chan, K., and F. Baker, "Configuration 2408 Guidelines for DiffServ Service Classes", RFC 4594, 2409 DOI 10.17487/RFC4594, August 2006, 2410 . 2412 [RFC5245] Rosenberg, J., "Interactive Connectivity Establishment 2413 (ICE): A Protocol for Network Address Translator (NAT) 2414 Traversal for Offer/Answer Protocols", RFC 5245, 2415 DOI 10.17487/RFC5245, April 2010, 2416 . 2418 [RFC7478] Holmberg, C., Hakansson, S., and G. Eriksson, "Web Real- 2419 Time Communication Use Cases and Requirements", RFC 7478, 2420 DOI 10.17487/RFC7478, March 2015, 2421 . 2423 [RFC7556] Anipko, D., Ed., "Multiple Provisioning Domain 2424 Architecture", RFC 7556, DOI 10.17487/RFC7556, June 2015, 2425 . 2427 [RFC7657] Black, D., Ed. and P. Jones, "Differentiated Services 2428 (Diffserv) and Real-Time Communication", RFC 7657, 2429 DOI 10.17487/RFC7657, November 2015, 2430 . 2432 [RFC8084] Fairhurst, G., "Network Transport Circuit Breakers", 2433 BCP 208, RFC 8084, DOI 10.17487/RFC8084, March 2017, 2434 . 2436 [RFC8095] Fairhurst, G., Ed., Trammell, B., Ed., and M. Kuehlewind, 2437 Ed., "Services Provided by IETF Transport Protocols and 2438 Congestion Control Mechanisms", RFC 8095, 2439 DOI 10.17487/RFC8095, March 2017, 2440 . 2442 Appendix A. Additional Properties 2444 The interface specified by this document represents the minimal 2445 common interface to an endpoint in the transport services 2446 architecture [I-D.ietf-taps-arch], based upon that architecture and 2447 on the minimal set of transport service features elaborated in 2448 [I-D.ietf-taps-minset]. However, the interface has been designed 2449 with extension points to allow the implementation of features beyond 2450 those in the minimal common interface: Protocol Selection Properties, 2451 Path Selection Properties, and Message Properties are open sets. 2452 Implementations of the interface are free to extend these sets to 2453 provide additional expressiveness to applications written on top of 2454 them. 2456 This appendix enumerates a few additional properties that could be 2457 used to enhance transport protocol and/or path selection, or the 2458 transmission of messages given a Protocol Stack that implements them. 2459 These are not part of the interface, and may be removed from the 2460 final document, but are presented here to support discussion within 2461 the TAPS working group as to whether they should be added to a future 2462 revision of the base specification. 2464 A.1. Experimental Transport Properties 2466 The following Transport Properties might be made available in 2467 addition to those specified in Section 5.2, Section 9.1, and 2468 Section 7.3. 2470 A.1.1. Cost Preferences 2472 [EDITOR'S NOTE: At IETF 103, opinions were that this property should 2473 stay, but it was also said that this is maybe not "on the right 2474 level". If / when moving it to the main text, note that this is 2475 meant to be applicable to a Preconnection or a Message.] 2477 Name: cost-preferences 2479 Type: Enumeration 2481 This property describes what an application prefers regarding 2482 monetary costs, e.g., whether it considers it acceptable to utilize 2483 limited data volume. It provides hints to the transport system on 2484 how to handle trade-offs between cost and performance or reliability. 2486 Possible values are: 2488 No Expense: Avoid transports associated with monetary cost 2490 Optimize Cost: Prefer inexpensive transports and accept service 2491 degradation 2493 Balance Cost: Use system policy to balance cost and other criteria 2495 Ignore Cost: Ignore cost, choose transport solely based on other 2496 criteria 2498 The default is "Balance Cost". 2500 Appendix B. Sample API definition in Go 2502 This document defines an abstract interface. To illustrate how this 2503 would map concretely into a programming language, an API interface 2504 definition in Go is available online at https://github.com/mami- 2505 project/postsocket. Documentation for this API - an illustration of 2506 the documentation an application developer would see for an instance 2507 of this interface - is available online at 2508 https://godoc.org/github.com/mami-project/postsocket. This API 2509 definition will be kept largely in sync with the development of this 2510 abstract interface definition. 2512 Appendix C. Relationship to the Minimal Set of Transport Services for 2513 End Systems 2515 [I-D.ietf-taps-minset] identifies a minimal set of transport services 2516 that end systems should offer. These services make all transport 2517 features offered by TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT 2518 available that 1) require interaction with the application, and 2) do 2519 not get in the way of a possible implementation over TCP or, with 2520 limitations, UDP. The following text explains how this minimal set 2521 is reflected in the present API. For brevity, this uses the list in 2522 Section 4.1 of [I-D.ietf-taps-minset], updated according to the 2523 discussion in Section 5 of [I-D.ietf-taps-minset]. 2525 [EDITOR'S NOTE: This is early text. In the future, this section will 2526 contain backward references, which we currently avoid because things 2527 are still being moved around and names / categories etc. are 2528 changing.] 2530 o Connect: 2531 "Initiate" Action. 2533 o Listen: 2534 "Listen" Action. 2536 o Specify number of attempts and/or timeout for the first 2537 establishment message: 2538 "Timeout for aborting Connection Establishment" Property, using a 2539 time value. 2541 o Disable MPTCP: 2542 "Parallel Use of Multiple Paths" Property. 2544 o Hand over a message to reliably transfer (possibly multiple times) 2545 before connection establishment: 2546 "InitiateWithSend" Action. 2548 o Hand over a message to reliably transfer during connection 2549 establishment: 2550 "InitiateWithSend" Action. 2552 o Change timeout for aborting connection (using retransmit limit or 2553 time value): 2554 "Timeout for aborting Connection" property, using a time value. 2556 o Timeout event when data could not be delivered for too long: 2557 "ConnectionError" Event. 2559 o Suggest timeout to the peer: 2560 TCP-specific Property: User Timeout. 2562 o Notification of Excessive Retransmissions (early warning below 2563 abortion threshold): 2564 "Notification of excessive retransmissions" property. 2566 o Notification of ICMP error message arrival: 2567 "Notification of ICMP soft error message arrival" property. 2569 o Choose a scheduler to operate between streams of an association: 2571 "Connection group transmission scheduler" property. 2573 o Configure priority or weight for a scheduler: 2574 "Priority (Connection)" property. 2576 o "Specify checksum coverage used by the sender" and "Disable 2577 checksum when sending": 2578 "Corruption Protection Length" property (value 0 to disable). 2580 o "Specify minimum checksum coverage required by receiver" and 2581 "Disable checksum requirement when receiving": 2582 "Required minimum coverage of the checksum for receiving" property 2583 (value 0 to disable). 2585 o "Specify DF" field and "Request not to bundle messages:" 2586 The "Singular Transmission" Message property combines both of 2587 these requests, i.e. if a request not to bundle messages is made, 2588 this also turns off DF in case of protocols that allow this (only 2589 UDP and UDP-Lite, which cannot bundle messages anyway). 2591 o Get max. transport-message size that may be sent using a non- 2592 fragmented IP packet from the configured interface: 2593 "Maximum Message size before fragmentation or segmentation" 2594 property. 2596 o Get max. transport-message size that may be received from the 2597 configured interface: 2598 "Maximum Message size on receive" property. 2600 o Obtain ECN field: 2601 "ECN" is a defined metadata value as part of the Message Receive 2602 Context. 2604 o "Specify DSCP field", "Disable Nagle algorithm", "Enable and 2605 configure a 'Low Extra Delay Background Transfer'": 2606 As suggested in Section 5.5 of [I-D.ietf-taps-minset], these 2607 transport features are collectively offered via the "Capacity 2608 profile" property. 2610 o Close after reliably delivering all remaining data, causing an 2611 event informing the application on the other side: 2612 This is offered by the "Close" Action with slightly changed 2613 semantics in line with the discussion in Section 5.2 of 2614 [I-D.ietf-taps-minset]. 2616 o "Abort without delivering remaining data, causing an event 2617 informing the application on the other side" and "Abort without 2618 delivering remaining data, not causing an event informing the 2619 application on the other side": 2620 This is offered by the "Abort" action without promising that this 2621 is signaled to the other side. If it is, a "ConnectionError" 2622 Event will fire at the peer. 2624 o "Reliably transfer data, with congestion control", "Reliably 2625 transfer a message, with congestion control" and "Unreliably 2626 transfer a message": 2627 Reliability is controlled via the "Reliable Data Transfer 2628 (Message)" Message property. Transmitting data without delimiters 2629 is done by not using a Framer. The choice of congestion control 2630 is provided via the "Congestion control" property. 2632 o Configurable Message Reliability: 2633 The "Lifetime" Message Property implements a time-based way to 2634 configure message reliability. 2636 o "Ordered message delivery (potentially slower than unordered)" and 2637 "Unordered message delivery (potentially faster than ordered)": 2638 The two transport features are controlled via the Message property 2639 "Ordered". 2641 o Request not to delay the acknowledgement (SACK) of a message: 2642 Should the protocol support it, this is one of the transport 2643 features the transport system can use when an application uses the 2644 Capacity Profile Property with value "Low Latency/Interactive". 2646 o Receive data (with no message delimiting): 2647 "Received" Event without using a Deframer. 2649 o Receive a message: 2650 "Received" Event. Section 5.1 of [I-D.ietf-taps-minset] discusses 2651 how messages can be obtained from a bytestream in case of 2652 implementation over TCP. Here, this is dealt with by Framers and 2653 Deframers. 2655 o Information about partial message arrival: 2656 "ReceivedPartial" Event. 2658 o Notification of send failures: 2659 "Expired" and "SendError" Events. 2661 o Notification that the stack has no more user data to send: 2662 Applications can obtain this information via the "Sent" Event. 2664 o Notification to a receiver that a partial message delivery has 2665 been aborted: 2667 "ReceiveError" Event. 2669 Authors' Addresses 2671 Brian Trammell (editor) 2672 Google 2673 Gustav-Gull-Platz 1 2674 8004 Zurich 2675 Switzerland 2677 Email: ietf@trammell.ch 2679 Michael Welzl (editor) 2680 University of Oslo 2681 PO Box 1080 Blindern 2682 0316 Oslo 2683 Norway 2685 Email: michawe@ifi.uio.no 2687 Theresa Enghardt 2688 TU Berlin 2689 Marchstrasse 23 2690 10587 Berlin 2691 Germany 2693 Email: theresa@inet.tu-berlin.de 2695 Godred Fairhurst 2696 University of Aberdeen 2697 Fraser Noble Building 2698 Aberdeen, AB24 3UE 2699 Scotland 2701 Email: gorry@erg.abdn.ac.uk 2702 URI: http://www.erg.abdn.ac.uk/ 2704 Mirja Kuehlewind 2705 ETH Zurich 2706 Gloriastrasse 35 2707 8092 Zurich 2708 Switzerland 2710 Email: mirja.kuehlewind@tik.ee.ethz.ch 2711 Colin Perkins 2712 University of Glasgow 2713 School of Computing Science 2714 Glasgow G12 8QQ 2715 United Kingdom 2717 Email: csp@csperkins.org 2719 Philipp S. Tiesel 2720 TU Berlin 2721 Marchstrasse 23 2722 10587 Berlin 2723 Germany 2725 Email: philipp@inet.tu-berlin.de 2727 Chris Wood 2728 Apple Inc. 2729 1 Infinite Loop 2730 Cupertino, California 95014 2731 United States of America 2733 Email: cawood@apple.com