idnits 2.17.00 (12 Aug 2021) /tmp/idnits41631/draft-trammell-taps-interface-00.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 is 1 instance of too long lines in the document, the longest one being 20 characters in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 261: '...e Local Endpoint MUST be specified if ...' RFC 2119 keyword, line 262: '...nections, but is OPTIONAL if it is use...' RFC 2119 keyword, line 263: '... Remote Endpoint MUST be specified in ...' RFC 2119 keyword, line 264: '...iate() Connections, but is OPTIONAL if...' RFC 2119 keyword, line 266: '... Remote Endpoint MUST both be specifie...' (3 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 01, 2018) is 1535 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: draft-ietf-taps-minset has been published as RFC 8923 == Outdated reference: draft-ietf-tsvwg-rtcweb-qos has been published as RFC 8837 == Outdated reference: draft-ietf-tsvwg-sctp-ndata has been published as RFC 8260 == Outdated reference: A later version (-02) exists of draft-pauly-taps-transport-security-01 -- Obsolete informational reference (is this intentional?): RFC 5245 (Obsoleted by RFC 8445, RFC 8839) Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 TAPS Working Group B. Trammell, Ed. 3 Internet-Draft ETH Zurich 4 Intended status: Informational M. Welzl, Ed. 5 Expires: September 2, 2018 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 01, 2018 20 An Abstract Application Layer Interface to Transport Services 21 draft-trammell-taps-interface-00 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 2, 2018. 50 Copyright Notice 52 Copyright (c) 2018 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 . . . . . . . . . . . . . . . . . . . . . . . . 3 68 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 3 69 3. Interface Design Principles . . . . . . . . . . . . . . . . . 4 70 4. API Summary . . . . . . . . . . . . . . . . . . . . . . . . . 5 71 5. Pre-Establishment Phase . . . . . . . . . . . . . . . . . . . 6 72 5.1. Specifying Endpoints . . . . . . . . . . . . . . . . . . 6 73 5.2. Specifying Transport Parameters . . . . . . . . . . . . . 7 74 5.2.1. Transport Parameters Object . . . . . . . . . . . . . 11 75 5.3. Specifying Security Parameters and Callbacks . . . . . . 12 76 6. Establishing Connections . . . . . . . . . . . . . . . . . . 13 77 6.1. Active Open: Initiate . . . . . . . . . . . . . . . . . . 13 78 6.2. Passive Open: Listen . . . . . . . . . . . . . . . . . . 14 79 6.3. Peer-to-Peer Establishment: Rendezvous . . . . . . . . . 15 80 6.4. Connection Groups . . . . . . . . . . . . . . . . . . . . 16 81 7. Sending Data . . . . . . . . . . . . . . . . . . . . . . . . 17 82 7.1. Send Parameters . . . . . . . . . . . . . . . . . . . . . 19 83 7.1.1. Lifetime . . . . . . . . . . . . . . . . . . . . . . 19 84 7.1.2. Niceness . . . . . . . . . . . . . . . . . . . . . . 19 85 7.1.3. Ordered . . . . . . . . . . . . . . . . . . . . . . . 20 86 7.1.4. Idempotent . . . . . . . . . . . . . . . . . . . . . 20 87 7.1.5. Corruption Protection Length . . . . . . . . . . . . 20 88 7.1.6. Immediate Acknowledgement . . . . . . . . . . . . . . 20 89 7.1.7. Instantaneous Capacity Profile . . . . . . . . . . . 21 90 7.2. Sender-side Framing . . . . . . . . . . . . . . . . . . . 21 91 8. Receiving Data . . . . . . . . . . . . . . . . . . . . . . . 22 92 8.1. Receiver-side De-framing over Stream Protocols . . . . . 23 93 9. Setting and Querying of Connection Properties . . . . . . . . 24 94 9.1. Protocol Properties . . . . . . . . . . . . . . . . . . . 25 95 10. Connection Termination . . . . . . . . . . . . . . . . . . . 27 96 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 97 12. Security Considerations . . . . . . . . . . . . . . . . . . . 27 98 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 27 99 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 100 14.1. Normative References . . . . . . . . . . . . . . . . . . 28 101 14.2. Informative References . . . . . . . . . . . . . . . . . 28 102 Appendix A. Additional Properties . . . . . . . . . . . . . . . 29 103 A.1. Protocol and Path Selection Properties . . . . . . . . . 29 104 A.1.1. Application Intents . . . . . . . . . . . . . . . . . 30 105 A.2. Protocol Properties . . . . . . . . . . . . . . . . . . . 32 106 A.3. Send Parameters . . . . . . . . . . . . . . . . . . . . . 32 107 Appendix B. Sample API definition in Go . . . . . . . . . . . . 32 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 33 110 1. Introduction 112 The BSD Unix Sockets API's SOCK_STREAM abstraction, by bringing 113 network sockets into the UNIX programming model, allowing anyone who 114 knew how to write programs that dealt with sequential-access files to 115 also write network applications, was a revolution in simplicity. It 116 would not be an overstatement to say that this simple API is the 117 reason the Internet won the protocol wars of the 1980s. SOCK_STREAM 118 is tied to the Transmission Control Protocol (TCP), specified in 1981 119 [RFC0793]. TCP has scaled remarkably well over the past three and a 120 half decades, but its total ubiquity has hidden an uncomfortable 121 fact: the network is not really a file, and stream abstractions are 122 too simplistic for many modern application programming models. 124 In the meantime, the nature of Internet access, and the variety of 125 Internet transport protocols, is evolving. The challenges that new 126 protocols and access paradigms present to the sockets API and to 127 programming models based on them inspire the design principles of a 128 new approach, which we outline in Section 3. 130 As a first step to realizing this design, [TAPS-ARCH] describes a 131 high-level architecture for transport services. This document builds 132 a modern abstract programming interface atop this architecture, 133 deriving specific path and protocol selection properties and 134 supported transport features from the analysis provided in [RFC8095] 135 and [I-D.ietf-taps-minset]. 137 2. Terminology and Notation 139 This API is described in terms of Objects, which an application can 140 interact with; Actions the application can perform on these Objects; 141 Events, which an Object can send to an application asynchronously; 142 and Parameters associated with these Actions and Events. 144 The following notations, which can be combined, are used in this 145 document: 147 o An Action creates an Object: ~~~ Object := Action() ~~~ 149 o An Action is performed on an Object: ~~~ Object.Action() ~~~ 151 o An Object sends an Event: ~~~ Object -> Event<> ~~~ 153 o An Action takes a set of Parameters; an Event contains a set of 154 Parameters: ~~~ Action(parameter, parameter, ...) / 155 Event ~~~ 157 Actions associated with no Object are Actions on the abstract 158 interface itself; they are equivalent to Actions on a per-application 159 global context. 161 How these abstract concepts map into concrete implementations of this 162 API in a given language on a given platform is largely dependent on 163 the features of the language and the platform. Actions could be 164 implemented as functions or method calls, for instance, and Events 165 could be implemented via callback passing or other asynchronous 166 calling conventions. The method for registering callbacks and 167 handlers is left as an implementation detail, with the caveat that 168 the interface for receiving Messages must require the application to 169 invoke the Connection.Receive() Action once per Message to be 170 received (see Section 8). 172 This specification treats Events and errors similarly, as errors, 173 just as any other Events, may occur asynchronously in network 174 applications. However, it is recommended that implementations of 175 this interface also return errors immediately, according to the error 176 handling idioms of the implementation platform, for errors which can 177 be immediately detected, such as inconsistency in transport 178 parameters. 180 3. Interface Design Principles 182 We begin with the architectural design principles defined in 183 [TAPS-ARCH]; from these, we derive and elaborate a set of principles 184 on which the design of the interface is based. The interface defined 185 in this document provides: 187 o A single interface to a variety of transport protocols to be used 188 in a variety of application design patterns, independent of the 189 properties of the application and the Protocol Stacks that will be 190 used at runtime, such that all common specialized features of 191 these protocol stacks are made available to the application as 192 necessary in a transport-independent way, to enable applications 193 written to a single API to make use of transport protocols in 194 terms of the features they provide; 196 o Explicit support for security properties as first-order transport 197 features, and for long-term caching of cryptographic identities 198 and parameters for associations among endpoints; 200 o Asynchronous Connection establishment, transmission, and 201 reception, allowing most application interactions with the 202 transport layer to be Event-driven, in line with developments in 203 modern platforms and programming languages; 205 o Explicit support for multistreaming and multipath transport 206 protocols, and the grouping of related Connections into Connection 207 Groups through cloning of Connections, to allow applications to 208 take full advantage of new transport protocols supporting these 209 features; and 211 o Atomic transmission of data, using application-assisted framing 212 and deframing where the underlying transport does not provide 213 these. 215 4. API Summary 217 The Transport Services Interface is the basic common abstract 218 application programming interface to the Transport Services 219 Architecture defined in [TAPS-ARCH]. An application primarily 220 interacts with this interface through two Objects, Preconnections and 221 Connections. A Preconnection represents a set of parameters and 222 constraints on the selection and configuration of paths and protocols 223 to establish a Connection with a remote endpoint. A Connection 224 represents a transport Protocol Stack on which data can be sent to 225 and received from a remote endpoint. Connections can be created from 226 Preconnections in three ways: by initiating the Preconnection (i.e., 227 actively opening, as in a client), through listening on the 228 Preconnection (i.e., passively opening, as in a server), or 229 rendezvousing on the Preconnection (i.e. peer to peer establishment). 231 Once a Connection is established, data can be sent on it in the form 232 of Messages. The interface supports the preservation of message 233 boundaries both via explicit Protocol Stack support, and via 234 application support through a deframing callback which finds message 235 boundaries in a stream. Messages are received asynchronously through 236 a callback registered by the application. Errors and other 237 notifications also happen asynchronously on the Connection. 239 In the following sections, we describe the details of application 240 interaction with Objects through Actions and Events in each phase of 241 a Connection, following the phases described in [TAPS-ARCH]. 243 5. Pre-Establishment Phase 245 The pre-establishment phase allows applications to specify parameters 246 for the Connections they're about to make, or to query the API about 247 potential connections they could make. 249 A Preconnection Object represents a potential Connection. It has 250 state that describes parameters of a Connection that might exist in 251 the future. This state comprises Local Endpoint and Remote Endpoint 252 Objects that denote the endpoints of the potential Connection (see 253 Section 5.1), the transport parameters (see Section 5.2), and the 254 security parameters (see Section 5.3): 256 Preconnection := NewPreconnection(LocalEndpoint, 257 RemoteEndpoint, 258 TransportParams, 259 SecurityParams) 261 The Local Endpoint MUST be specified if the Preconnection is used to 262 Listen() for incoming Connections, but is OPTIONAL if it is used to 263 Initiate() connections. The Remote Endpoint MUST be specified in the 264 Preconnection is used to Initiate() Connections, but is OPTIONAL if 265 it is used to Listen() for incoming Connections. The Local Endpoint 266 and the Remote Endpoint MUST both be specified if a peer-to-peer 267 Rendezvous is to occur based on the Preconnection. 269 Framers (see Section 7.2) and deframers (see Section 8.1), if 270 necessary, should be bound to the Preconnection during pre- 271 establishment. 273 Preconnections, as Connections, can be cloned, in order to establish 274 Connection groups before Connection initiation; see Section 6.4 for 275 details. 277 5.1. Specifying Endpoints 279 The transport services API uses the Local Endpoint and Remote 280 Endpoint types to refer to the endpoints of a transport connection. 281 Subtypes of these represent various different types of endpoint 282 identifiers, such as IP addresses, DNS names, and interface names, as 283 well as port numbers and service names. 285 RemoteSpecifier := NewRemoteEndpoint() 286 RemoteSpecifier.WithHostname("example.com") 287 RemoteSpecifier.WithService("https") 289 RemoteSpecifier := NewRemoteEndpoint() 290 RemoteSpecifier.WithIPv6Address(2001:db8:4920:e29d:a420:7461:7073:0a) 291 RemoteSpecifier.WithPort(443) 293 RemoteSpecifier := NewRemoteEndpoint() 294 RemoteSpecifier.WithIPv4Address(192.0.2.21) 295 RemoteSpecifier.WithPort(443) 297 LocalSpecifier := NewLocalEndpoint() 298 LocalSpecifier.WithInterface("en0") 299 LocalSpecifier.WithPort(443) 301 LocalSpecifier := NewLocalEndpoint() 302 LocalSpecifier.WithStunServer(address, port, credentials) 304 Implementations may also support additional endpoint representations 305 and provide a single NewEndpoint() call that takes different endpoint 306 representations. 308 Multiple endpoint identifiers can be specified for each Local 309 Endpoint and RemoteEndoint. For example, a Local Endpoint could be 310 configured with two interface names, or a Remote Endpoint could be 311 specified via both IPv4 and IPv6 addresses. The multiple identifiers 312 refer to the same endpoint. 314 The transport services API will resolve names internally, when the 315 Initiate(), Listen(), or Rendezvous() method is called establish a 316 Connection. The API does not need the application to resolve names, 317 and premature name resolution can damage performance by limiting the 318 scope for alternate path discovery during Connection establishment. 319 The Resolve() method is, however, provided to resolve a Local 320 Endpoint or a Remote Endpoint in cases where this is required, for 321 example with some NAT traversal protocols (see Section 6.3). 323 5.2. Specifying Transport Parameters 325 A Preconnection Object holds parameters reflecting the application's 326 requirements and preferences for the transport. These include 327 protocol and path selection parameters, as well as Generic and 328 Specific Protocol Properties for configuration of the detailed 329 operation of the selected Protocol Stacks. 331 All Transport Parameters are organized within a single namespace 332 shared with Send Parameters (see Section 7.1). All transport 333 parameters take paremeter-specific values. Protocol and Path 334 Selection properties additionally take one of five preference levels, 335 though not all preference levels make sense with all such properties. 336 Note that it is possible for a set of specified transport parameters 337 to be internally inconsistent, or for preferences to be inconsistent 338 with the later use of the API by the application. Application 339 developers should reduce inconsistency by only using the most 340 stringent preference levels when failure to meet a preference would 341 break the application's functionality (e.g. the Reliable Data 342 Transfer preference, which is a core assumption of many application 343 protocols). Implementations of this interface should also raise 344 errors in configuration as early as possible, to help ensure these 345 inconsistencies are caught early in the development process. 347 The protocol(s) and path(s) selected as candidates during Connection 348 establishment are determined by a set of properties. Since there 349 could be paths over which some transport protocols are unable to 350 operate, or remote endpoints that support only specific network 351 addresses or transports, transport protocol selection is necessarily 352 tied to path selection. This may involve choosing between multiple 353 local interfaces that are connected to different access networks. 355 To reflect the needs of an individual Connection, they can be 356 specified with five different preference levels: 358 +------------+------------------------------------------------------+ 359 | Preference | Effect | 360 +------------+------------------------------------------------------+ 361 | Require | Select only protocols/paths providing the property, | 362 | | fail otherwise | 363 | | | 364 | Prefer | Prefer protocols/paths providing the property, | 365 | | proceed otherwise | 366 | | | 367 | Ignore | Cancel any default preference for this property | 368 | | | 369 | Avoid | Prefer protocols/paths not providing the property, | 370 | | proceed otherwise | 371 | | | 372 | Prohibit | Select only protocols/paths not providing the | 373 | | property, fail otherwise | 374 +------------+------------------------------------------------------+ 376 An implementation of this interface must provide sensible defaults 377 for protocol and path selection properties. The defaults given for 378 each property below represent a configuration that can be implemented 379 over TCP. An alternate set of default Protocol Selection Properties 380 would represent a configuration that can be implemented over UDP. 382 The following properties can be used during Protocol and Path 383 selection: 385 o Reliable Data Transfer: This boolean property specifies whether 386 the application needs the transport protocol to ensure that data 387 is received completely and without corruption on the other side. 388 This also entails being notified when a Connection is closed or 389 aborted. This property applies to Connections and Connection 390 Groups. This is a strict requirement. The default is to enable 391 Reliable Data Transfer. 393 o Preservation of data ordering: This boolean property specifies 394 whether the application needs the transport protocol to assure 395 that data is received by the application on the other end in the 396 same order as it was sent. This property applies to Connections 397 and Connection Groups. This is a strict requirement. The default 398 is to preserve data ordering. 400 o Configure reliability on a per-Message basis: This boolean 401 property specifies whether an application considers it useful to 402 indicate its reliability requirements on a per-Message basis. 403 This property applies to Connections and Connection Groups. This 404 is not a strict requirement. The default is to not have this 405 option. 407 o Use 0-RTT session establishment with an idempotent Message: This 408 boolean property specifies whether an application would like to 409 supply a Message to the transport protocol before Connection 410 establishment, which will then be reliably transferred to the 411 other side before or during Connection establishment, potentially 412 multiple times. See also Section 7.1.4. This is a strict 413 requirement. The default is to not have this option. 415 o Multiplex Connections: This boolean property specifies that the 416 application would prefer multiple Connections between the same 417 endpoints within a Connection Group to be multiplexed onto a 418 single underlying transport connection where possible, for reasons 419 of efficiency. This is not a strict requirement. The default is 420 to not have this option. 422 o Notification of excessive retransmissions: This boolean property 423 specifies whether an application considers it useful to be 424 informed in case sent data was retransmitted more often than a 425 certain threshold. This property applies to Connections and 426 Connection Groups. This is not a strict requirement. The default 427 is to have this option. 429 o Notification of ICMP error message arrival: This boolean property 430 specifies whether an application considers it useful to be 431 informed when an ICMP error message arrives. This property 432 applies to Connections and Connection Groups. This is not a 433 strict requirement. The default is to have this option. 435 o Control checksum coverage on sending or receiving: This boolean 436 property specifies whether the application considers it useful to 437 enable / disable / configure a checksum when sending data, or 438 decide whether to require a checksum or not when receiving data. 439 This property applies to Connections and Connection Groups. This 440 is not a strict requirement, as it signifies a reduction in 441 reliability. The default is full checksum coverage without being 442 able to change it, and requiring a checksum when receiving. 444 o Interface Type: This enumerated property specifies which kind of 445 access network interface, e.g., WiFi, Ethernet, or LTE, to prefer 446 over others for this Connection, in case they are available. In 447 general, Interface Types should be used only with the "Prefer" and 448 "Prohibit" preference level. Specifically, using the "Require" 449 preference level for Interface Type may limit path selection in a 450 way that is detrimental to connectivity. The default is to use 451 the default interface configured in the system policy. 453 o Capacity Profile: This enumerated property specifies the 454 application's expectation of the dominating traffic pattern for 455 this Connection. The Capacity Profile should only be used with 456 the "Prefer" preference level; other preference levels make no 457 sense for profiles. The following values are valid for Capacity 458 Profile: 460 Default: The application makes no representation about its 461 expected capacity profile. No special optimizations of the 462 tradeoff between delay, delay variation, and bandwidth 463 efficiency should be made when selecting and configuring 464 stacks. 466 Interactive/Low Latency: The application is interactive. 467 Response time (latency) should be optimized at the expense of 468 bandwidth efficiency and delay variation. This can be used by 469 the system to disable the coalescing of multiple small Messages 470 into larger packets (Nagle's algorithm), to prefer lower- 471 latency paths, signal a preference for lower-latency, higher- 472 loss treatment, and so on. 474 Constant Rate: The application expects to send/receive data at a 475 constant rate after Connection establishment. Delay and delay 476 variation should be optimized at the expense of bandwidth 477 efficiency. This implies that the Connection may fail if the 478 desired rate cannot be maintained across the Path. A transport 479 may interpret this capacity profile as preferring a circuit 480 breaker [RFC8084] to a rate adaptive congestion controller. 482 Scavenger/Bulk: The application is not interactive. It expects 483 to send/receive a large amount of data, without any urgency. 484 This can be used to select protocol stacks with scavenger 485 transmission control, to signal a preference for less-than- 486 best-effort treatment, and so on. 488 In addition to protocol and path selection properties, the transport 489 parameters may also contain Generic and/or Specific Protocol 490 Properties (see Section 9.1). These properties will be passed to the 491 selected candidate Protocol Stack(s) to configure them before 492 candidate Connection establishment. 494 5.2.1. Transport Parameters Object 496 All transport parameters used in the pre-establishment phase are 497 collected in a TransportParameters Object that is passed to the 498 Preconnection Object. 500 TransportParameters := NewTransportParameters() 502 The Individual parameters are then added to the TransportParameters 503 Object. While Protocol Properties use the "add" call, Transport 504 Preferences use special calls for the levels defined in Section 5.2. 506 TransportParameters.Add(parameter, value) 508 TransportParameters.Require(preference) 509 TransportParameters.Prefer(preference) 510 TransportParameters.Ignore(preference) 511 TransportParameters.Avoid(preference) 512 TransportParameters.Prohibit(preference) 514 For an existing Connection, the Transport Parameters can be queried 515 any time by using the following call on the Connection Object: 517 TransportParameters := Connection.GetTransportParameters() 519 Note that most properties are only considered for Connection 520 establishment and can not be changed after a Connection is 521 established; however, they can be queried. See Section 9. 523 A Connection gets its Transport Parameters either by being explicitly 524 configured via a Preconnection, or by inheriting them from an 525 antecedent via cloning; see Section 6.4 for more. 527 5.3. Specifying Security Parameters and Callbacks 529 Common parameters such as TLS ciphersuites are known to 530 implementations. Clients SHOULD use common safe defaults for these 531 values whenever possible. However, as discussed in 532 [I-D.pauly-taps-transport-security], many transport security 533 protocols require specific security parameters and constraints from 534 the client at the time of configuration and actively during a 535 handshake. These configuration parameters are created as follows 537 SecurityParameters := NewSecurityParameters() 539 Security configuration parameters and sample usage follow: 541 o Local identity and private keys: Used to perform private key 542 operations and prove one's identity to the Remote Endpoint. 543 (Note, if private keys are not available, e.g., since they are 544 stored in HSMs, handshake callbacks MUST be used. See below for 545 details.) 547 SecurityParameters.AddIdentity(identity) 548 SecurityParameters.AddPrivateKey(privateKey, publicKey) 550 o Supported algorithms: Used to restrict what parameters are used by 551 underlying transport security protocols. When not specified, 552 these algorithms SHOULD default to known and safe defaults for the 553 system. Parameters include: ciphersuites, supported groups, and 554 signature algorithms. 556 SecurityParameters.AddSupportedGroup(22) // secp256k1 557 SecurityParameters.AddCiphersuite(0xCCA9) // TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 558 SecurityParameters.AddSignatureAlgorithm(7) // ed25519 560 o Session cache: Used to tune cache capacity, lifetime, re-use, and 561 eviction policies, e.g., LRU or FIFO. 563 SecurityParameters.SetSessionCacheCapacity(1024) // 1024 elements 564 SecurityParameters.SetSessionCacheLifetime(24*60*60) // 24 hours 565 SecurityParameters.SetSessionCacheReuse(1) // One-time use 567 o Pre-shared keying material: Used to install pre-shared keying 568 material established out-of-band. Each pre-shared keying material 569 is associated with some identity that typically identifies its use 570 or has some protocol-specific meaning to the Remote Endpoint. 572 SecurityParameters.AddPreSharedKey(key, identity) 574 Security decisions, especially pertaining to trust, are not static. 575 Thus, once configured, parameters must also be supplied during live 576 handshakes. These are best handled as client-provided callbacks. 577 Security handshake callbacks include: 579 o Trust verification callback: Invoked when a Remote Endpoint's 580 trust must be validated before the handshake protocol can proceed. 582 TrustCallback := NewCallback({ 583 // Handle trust, return the result 584 }) 585 SecurityParameters.SetTrustVerificationCallback(trustCallback) 587 o Identity challenge callback: Invoked when a private key operation 588 is required, e.g., when local authentication is requested by a 589 remote. 591 ChallengeCallback := NewCallback({ 592 // Handle challenge 593 }) 594 SecurityParameters.SetIdentityChallengeCallback(challengeCallback) 596 Like transport parameters, security parameters are inherited during 597 cloning (see Section 6.4). 599 6. Establishing Connections 601 Before a Connection can be used for data transfer, it must be 602 established. Establishment ends the pre-establishment phase; all 603 transport and cryptographic parameter specification must be complete 604 before establishment, as these parameters will be used to select 605 candidate Paths and Protocol Stacks for the Connection. 606 Establishment may be active, using the Initiate() Action; passive, 607 using the Listen() Action; or simultaneous for peer-to-peer, using 608 the Rendezvous() Action. These Actions are described in the 609 subsections below. 611 6.1. Active Open: Initiate 613 Active open is the Action of establishing a Connection to a Remote 614 Endpoint presumed to be listening for incoming Connection requests. 615 Active open is used by clients in client-server interactions. Active 616 open is supported by this interface through the Initiate Action: 618 Connection := Preconnection.Initiate() 619 Before calling Initiate, the caller must have populated a 620 Preconnection Object with a Remote Endpoint specifier, optionally a 621 Local Endpoint specifier (if not specified, the system will attempt 622 to determine a suitable Local Endpoint), as well as all parameters 623 necessary for candidate selection. After calling Initiate, no 624 further parameters may be bound to the Connection. The Initiate() 625 call consumes the Preconnection and creates a Connection Object. A 626 Preconnection can only be initiated once. 628 Once Initiate is called, the candidate Protocol Stack(s) may cause 629 one or more candidate transport-layer connections to be created to 630 the specified remote endpoint. The caller may immediately begin 631 sending Messages on the Connection (see Section 7) after calling 632 Initate(); note that any idempotent data sent while the Connection is 633 being established may be sent multiple times or on multiple 634 candidates. 636 The following Events may be sent by the Connection after Initiate() 637 is called: 639 Connection -> Ready<> 641 The Ready Event occurs after Initiate has established a transport- 642 layer connection on at least one usable candidate Protocol Stack over 643 at least one candidate Path. No Receive Events (see Section 8) will 644 occur before the Ready Event for Connections established using 645 Initiate. 647 Connection -> InitiateError<> 649 An InitiateError occurs either when the set of transport and 650 cryptographic parameters cannot be fulfilled on a Connection for 651 initiation (e.g. the set of available Paths and/or Protocol Stacks 652 meeting the constraints is empty) or reconciled with the local and/or 653 remote endpoints; when the remote specifier cannot be resolved; or 654 when no transport-layer connection can be established to the remote 655 endpoint (e.g. because the remote endpoint is not accepting 656 connections, or the application is prohibited from opening a 657 Connection by the operating system). 659 6.2. Passive Open: Listen 661 Passive open is the Action of waiting for Connections from remote 662 endpoints, commonly used by servers in client-server interactions. 663 Passive open is supported by this interface through the Listen 664 Action: 666 Preconnection.Listen() 667 Before calling Listen, the caller must have initialized the 668 Preconnection during the pre-establishment phase with a Local 669 Endpoint specifier, as well as all parameters necessary for Protocol 670 Stack selection. A Remote Endpoint may optionally be specified, to 671 constrain what Connections are accepted. The Listen() Action 672 consumes the Preconnection. Once Listen() has been called, no 673 further parameters may be bound to the Preconnection, and no 674 subsequent establishment call may be made on the Preconnection. 676 Preconnection -> ConnectionReceived 678 The ConnectionReceived Event occurs when a Remote Endpoint has 679 established a transport-layer connection to this Preconnection (for 680 Connection-oriented transport protocols), or when the first Message 681 has been received from the Remote Endpoint (for Connectionless 682 protocols), causing a new Connection to be created. The resulting 683 Connection is contained within the ConnectionReceived event, and is 684 ready to use as soon as it is passed to the application via the 685 event. 687 Preconnection -> ListenError<> 689 A ListenError occurs either when the Preconnection cannot be 690 fulfilled for listening, when the Local Endpoint (or Remote Endpoint, 691 if specified) cannot be resolved, or when the application is 692 prohibited from listening by policy. 694 6.3. Peer-to-Peer Establishment: Rendezvous 696 Simultaneous peer-to-peer Connection establishment is supported by 697 the Rendezvous() Action: 699 Preconnection.Rendezvous() 701 The Preconnection Object must be specified with both a Local Endpoint 702 and a Remote Endpoint, and also the transport and security parameters 703 needed for Protocol Stack selection. The Rendezvous() Action causes 704 the Preconnection to listen on the Local Endpoint for an incoming 705 Connection from the Remote Endpoint, while simultaneously trying to 706 establish a Connection from the Local Endpoint to the Remote 707 Endpoint. This corresponds to a TCP simultaneous open, for example. 709 The Rendezvous() Action consumes the Preconnection. Once 710 Rendezvous() has been called, no further parameters may be bound to 711 the Preconnection, and no subsequent establishment call may be made 712 on the Preconnection. 714 Preconnection -> RendezvousDone 715 The RendezvousDone<> Event occurs when a Connection is established 716 with the Remote Endpoint. For Connection-oriented transports, this 717 occurs when the transport-layer connection is established; for 718 Connectionless transports, it occurs when the first Message is 719 received from the Remote Endpoint. The resulting Connection is 720 contained within the RendezvousDone<> Event, and is ready to use as 721 soon as it is passed to the application via the Event. 723 Preconnection -> RendezvousError 725 An RendezvousError occurs either when the Preconnection cannot be 726 fulfilled for listening, when the Local Endpoint or Remote Endpoint 727 cannot be resolved, when no transport-layer connection can be 728 established to the Remote Endpoint, or when the application is 729 prohibited from rendezvous by policy. 731 When using some NAT traversal protocols, e.g., ICE [RFC5245], it is 732 expected that the Local Endpoint will be configured with some method 733 of discovering NAT bindings, e.g., a STUN server. In this case, the 734 Local Endpoint may resolve to a mixture of local and server reflexive 735 addresses. The Resolve() method on the Preconnection can be used to 736 discover these bindings: 738 PreconnectionBindings := Preconnection.Resolve() 740 The Resolve() call returns a list of Preconnection Objects, that 741 represent the concrete addresses, local and server reflexive, on 742 which a Rendezvous() for the Preconnection will listen for incoming 743 Connections. This list can be passed to a peer via a signalling 744 protocol, such as SIP or WebRTC, to configure the remote. 746 6.4. Connection Groups 748 Groups of Preconnections or Connections can be created using the 749 Clone Action: 751 Preconnection := Preconnection.Clone() 753 Connection := Connection.Clone() 755 Calling Clone on a Connection yields a group of two Connections: the 756 parent Connection on which Clone was called, and the resulting clone 757 Connection. These connections are "entangled" with each other, and 758 become part of a Connection group. Calling Clone on any of these two 759 Connections adds a third Connection to the group, and so on. 760 Connections in a Connection Group share all their properties, and 761 changing the properties on one Connection in the group changes the 762 property for all others. 764 Calling Clone on a Preconnection yields a Preconnection with the same 765 parameters, which is entangled with the parent Preconnection: all the 766 Connections created from entangled Preconnections will be entangled 767 as if they had been cloned, and will belong to the same Connection 768 Group. 770 Establishing a Connection from a cloned Preconnection will not cause 771 Connections for other entangled Preconnections to be established; 772 each such Connection must be established separately. Changes to the 773 parameters of a Preconnection entangled with a Preconnection from 774 which a Connection has already been established will fail. Calling 775 Clone on a Preconnection may be taken by the system an implicit 776 signal that Protocol Stacks supporting multiplexed Connections for 777 efficient Connection Grouping are preferred by the application. 779 There is only one Protocol Property that is not entangled, i.e., it 780 is a separate per-Connection Property for individual Connections in 781 the group: niceness. Niceness works as in Section 7.1.2: when 782 allocating available network capacity among Connections in a 783 Connection Group, sends on Connections with higher Niceness values 784 will be prioritized over sends on Connections with lower Niceness 785 values. An ideal transport system implementation would assign the 786 Connection the capacity share (M-N) x C / M, where N is the 787 Connection's Niceness value, M is the maximum Niceness value used by 788 all Connections in the group and C is the total available capacity. 789 However, the niceness setting is purely advisory, and no guarantees 790 are given about capacity allocation and each implementation is free 791 to implement exact capacity allocation as it sees fit. 793 7. Sending Data 795 Once a Connection has been established, it can be used for sending 796 data. Data is sent by passing a Message Object and additional 797 parameters Section 7.1 to the Send Action on an established 798 Connection: 800 Connection.Send(Message, sendParameters) 802 The type of the Message to be passed is dependent on the 803 implementation, and on the constraints on the Protocol Stacks implied 804 by the Connection's transport parameters. It may itself contain an 805 array of octets to be transmitted in the transport protocol payload, 806 or be transformable to an array of octets by a sender-side framer 807 (see Section 7.2). 809 Some transport protocols can deliver arbitrarily sized Messages, but 810 other protocols constrain the maximum Message size. Applications can 811 query the protocol property Maximum Message Size on Send to determine 812 the maximum size. 814 There may also be system and Protocol Stack dependent limits on the 815 size of a Message which can be transmitted atomically. For that 816 reason, the Message object passed to the Send action may also be a 817 partial Message, either representing the whole data object and 818 information about the range of bytes to send from it, or an object 819 referring back to the larger whole Message. The details of partial 820 Message sending are implementation-dependent. 822 If Send is called on a Connection which has not yet been established, 823 an Initiate Action will be implicitly performed simultaneously with 824 the Send. Used together with the Idempotent property (see 825 Section 7.1.4), this can be used to send data during establishment 826 for 0-RTT session resumption on Protocol Stacks that support it. 828 Like all Actions in this interface, the Send Action is asynchronous. 830 Connection -> Sent 832 The Sent Event occurs when a previous Send Action has completed, 833 i.e., when the data derived from the Message has been passed down or 834 through the underlying Protocol Stack and is no longer the 835 responsibility of the implementation of this interface. The exact 836 disposition of the Message when the Sent Event occurs is specific to 837 the implementation and the constraints on the Protocol Stacks implied 838 by the Connection's transport parameters. The Sent Event contains an 839 implementation-specific reference to the Message to which it applies. 841 Sent Events allow an application to obtain an understanding of the 842 amount of buffering it creates. That is, if an application calls the 843 Send Action multiple times without waiting for a Sent Event, it has 844 created more buffer inside the transport system than an application 845 that only issues a Send after this Event fires. 847 Connection -> Expired 849 The Expired Event occurs when a previous Send Action expired before 850 completion; i.e. when the Message was not sent before its Lifetime 851 (see Section 7.1.1) expired. This is separate from SendError, as it 852 is an expected behavior for partially reliable transports. The 853 Expired Event contains an implementation-specific reference to the 854 Message to which it applies. 856 Connection -> SendError 857 A SendError occurs when a Message could not be sent due to an error 858 condition: an attempt to send a Message which is too large for the 859 system and Protocol Stack to handle, some failure of the underlying 860 Protocol Stack, or a set of send parameters not consistent with the 861 Connection's transport parameters. The SendError contains an 862 implementation-specific reference to the Message to which it applies. 864 7.1. Send Parameters 866 The Send Action takes per-Message send parameters which control how 867 the contents will be sent down to the underlying Protocol Stack and 868 transmitted. 870 If Send Parameters should be overridden for a specific Message, an 871 empty sent parameter Object can be acquired and all desired Send 872 Parameters can be added to that Object. A sendParameters Object can 873 be reused for sending multiple contents with the same properties. 875 SendParameters := NewSendParameters() 876 SendParameters.Add(parameter, value) 878 The Send Parameters share a single namespace with the Transport 879 Parameters (see Section 5.2). This allows the specification of 880 Protocol Properties that can be overridden on a per-Message basis. 882 Send Parameters may be inconsistent with the properties of the 883 Protocol Stacks underlying the Connection on which a given Message is 884 sent. For example, infinite Lifetime is not possible on a Message 885 over a Connection not providing reliability. Sending a Message with 886 Send Properties inconsistent with the Transport Preferences on the 887 Connection yields an error. 889 The following send parameters are supported: 891 7.1.1. Lifetime 893 Lifetime specifies how long a particular Message can wait to be sent 894 to the remote endpoint before it is irrelevant and no longer needs to 895 be (re-)transmitted. When a Message's Lifetime is infinite, it must 896 be transmitted reliably. The type and units of Lifetime are 897 implementation-specific. 899 7.1.2. Niceness 901 Niceness represents an unbounded hierarchy of priorities of Messages, 902 relative to other Messages sent over the same Connection and/or 903 Connection Group (see Section 6.4). It is most naturally represented 904 as a non-negative integer. A Message with Niceness 0 will yield to a 905 Message with Niceness 1, which will yield to a Message with Niceness 906 2, and so on. Niceness may be used as a sender-side scheduling 907 construct only, or be used to specify priorities on the wire for 908 Protocol Stacks supporting prioritization. 910 Note that this inversion of normal schemes for expressing priority 911 has a convenient property: priority increases as both Niceness and 912 Lifetime decrease. 914 7.1.3. Ordered 916 Ordered is a boolean property. If true, this Message should be 917 delivered after the last Message passed to the same Connection via 918 the Send Action; if false, this Message may be delivered out of 919 order. 921 7.1.4. Idempotent 923 Idempotent is a boolean property. If true, the application-layer 924 entity in the Message is safe to send to the remote endpoint more 925 than once for a single Send Action. It is used to mark data safe for 926 certain 0-RTT establishment techniques, where retransmission of the 927 0-RTT data may cause the remote application to receive the Message 928 multiple times. 930 7.1.5. Corruption Protection Length 932 This numeric property specifies the length of the section of the 933 Message, starting from byte 0, that the application assumes will be 934 received without corruption due to lower layer errors. It is used to 935 specify options for simple integrity protection via checksums. By 936 default, the entire Message is protected by checksum. A value of 0 937 means that no checksum is required, and a special value (e.g. -1) can 938 be used to indicate the default. Only full coverage is guaranteed, 939 any other requests are advisory. 941 7.1.6. Immediate Acknowledgement 943 This boolean property specifies, if true, that an application wants 944 this Message to be acknowledged immediately by the receiver. In case 945 of reliable transmission, this informs the transport protocol on the 946 sender side faster that it can remove the Message from its buffer; 947 therefore this property can be useful for latency-critical 948 applications that maintain tight control over the send buffer (see 949 Section 7). 951 7.1.7. Instantaneous Capacity Profile 953 This enumerated property specifies the application's preferred 954 tradeoffs for sending this Message; it is a per-Message override of 955 the Capacity Profile protocol and path selection property (see 956 Section 5.2). 958 The following values are valid for Instantaneous Capacity Profile: 960 Default: No special optimizations of the tradeoff between delay, 961 delay variation, and bandwidth efficiency should be made when 962 sending this message. 964 Interactive/Low Latency: Response time (latency) should be optimized 965 at the expense of bandwidth efficiency and delay variation when 966 sending this message. This can be used by the system to disable 967 the coalescing of multiple small Messages into larger packets 968 (Nagle's algorithm), to signal a preference for lower-latency, 969 higher-loss treatment, and so on. 971 Constant Rate: Delay and delay variation should be optimized at the 972 expense of bandwidth efficiency. 974 Scavenger/Bulk: This Message may be sent at the system's leisure. 975 This can be used to signal a preference for less-than-best-effort 976 treatment, to delay sending until lower-cost paths are available, 977 and so on. 979 7.2. Sender-side Framing 981 Sender-side framing allows a caller to provide the interface with a 982 function that takes a Message of an appropriate application-layer 983 type and returns an array of octets, the on-the-wire representation 984 of the Message to be handed down to the Protocol Stack. It consists 985 of a Framer Object with a single Action, Frame. Since the Framer 986 depends on the protocol used at the application layer, it is bound to 987 the Preconnection during the pre-establishment phase: 989 Preconnection.FrameWith(Framer) 991 OctetArray := Framer.Frame(Message) 993 Sender-side framing is a convenience feature of the interface, for 994 parity with receiver-side framing (see Section 8.1). 996 8. Receiving Data 998 Once a Connection is established, Messages may be received on it. 999 The application can indicate that it is ready to receive Messages by 1000 calling Receive() on the Connection. 1002 Connection.Receive(ReceiveHandler, maxLength) 1004 Receive takes a ReceiveHandler, which can handle the Received Event 1005 and the ReceiveError error. Each call to Receive will result in at 1006 most one Received event being sent to the handler, though 1007 implementations may provide convenience functions to indicate 1008 readiness to receive a larger but finite number of Messages with a 1009 single call. This allows an application to provide backpressure to 1010 the transport stack when it is temporarily not ready to receive 1011 messages. 1013 Receive also takes an optional maxLength argument, the maximum size 1014 (in bytes of data) Message the application is currently prepared to 1015 receive. The default value for maxLength is infinite. If an 1016 incoming Message is larger than the minimum of this size and the 1017 maximum Message size on receive for the Connection's Protocol Stack, 1018 it will be received as a partial Message. Note that maxLength does 1019 not guarantee that the application will receive that many bytes if 1020 they are available; the interface may return partial Messages smaller 1021 than maxLength according to implementation constraints. 1023 Connection -> Received 1025 As with sending, the type of the Message to be passed is dependent on 1026 the implementation, and on the constraints on the Protocol Stacks 1027 implied by the Connection's transport parameters. The Message may 1028 also contain metadata from protocols in the Protocol Stack; which 1029 metadata is available is Protocol Stack dependent. In particular, 1030 when this information is available, the value of the Explicit 1031 Congestion Notification (ECN) field is contained in such metadata. 1032 This information can be used for logging and debugging purposes, and 1033 for building applications which need access to information about the 1034 transport internals for their own operation. 1036 The Message Object must provide some method to retrieve an octet 1037 array containing application data, corresponding to a single message 1038 within the underlying Protocol Stack's framing. See Section 8.1 for 1039 handling framing in situations where the Protocol Stack provides 1040 octet-stream transport only. 1042 The Message Object passed to Received is complete and atomic, unless 1043 one of the following conditions holds: 1045 o the underlying Protocol Stack supports message boundary 1046 preservation, and the size of the Message is larger than the 1047 buffers available for a single message; 1049 o the underlying Protocol Stack does not support message boundary 1050 preservation, and the deframer (see Section 8.1) cannot determine 1051 the end of the message using the buffer space it has available; or 1053 o the underlying Protocol Stack does not support message boundary 1054 preservation, and no deframer was supplied by the application 1056 The Message Object passed to Received will indicate one of the 1057 following: 1059 1. this is a complete message; 1061 2. this is a partial message containing a section of a message with 1062 a known message boundary (made partial for local buffering 1063 reasons, either by the underlying Protocol Stack or the 1064 deframer). In this case, the Message Object passed to Received 1065 may contain the byte offset of the data in the partial Message 1066 within the full Message, an indication whether this is the last 1067 (highest-offset) partial Message in the full Message, and an 1068 optional reference to the full Message it belongs to; or 1070 3. this is a partial message containing data with no definite 1071 message boundary, i.e. the only known message boundary is given 1072 by termination of the Connection 1074 Note that in the absence of message boundary preservation and without 1075 deframing, the entire Connection is represented as one large message 1076 of indeterminate length. 1078 Connection -> ReceiveError<> 1080 A ReceiveError occurs when data is received by the underlying 1081 Protocol Stack that cannot be fully retrieved or deframed, or when 1082 some other indication is received that reception has failed. Such 1083 conditions that irrevocably lead the the termination of the 1084 Connection are signaled using ConnectionError instead (see 1085 Section 10). 1087 8.1. Receiver-side De-framing over Stream Protocols 1089 The Receive Event is intended to be fired once per application-layer 1090 Message sent by the remote endpoint; i.e., it is a desired property 1091 of this interface that a Send at one end of a Connection maps to 1092 exactly one Receive on the other end. This is possible with Protocol 1093 Stacks that provide message boundary preservation, but is not the 1094 case over Protocol Stacks that provide a simple octet stream 1095 transport. 1097 For preserving message boundaries over stream transports, this 1098 interface provides receiver-side de-framing. This facility is based 1099 on the observation that, since many of our current application 1100 protocols evolved over TCP, which does not provide message boundary 1101 preservation, and since many of these protocols require message 1102 boundaries to function, each application layer protocol has defined 1103 its own framing. A Deframer allows an application to push this de- 1104 framing down into the interface, in order to transform an octet 1105 stream into a sequence of Messages. 1107 Concretely, receiver-side de-framing allows a caller to provide the 1108 interface with a function that takes an octet stream, as provided by 1109 the underlying Protocol Stack, reads and returns a single Message of 1110 an appropriate type for the application and platform, and leaves the 1111 octet stream at the start of the next Message to deframe. It 1112 consists of a Deframer Object with a single Action, Deframe. Since 1113 the Deframer depends on the protocol used at the application layer, 1114 it is bound to the Preconnection during the pre-establishment phase: 1116 Preconnection.DeframeWith(Deframer) 1118 Message := Deframer.Deframe(OctetStream, ...) 1120 9. Setting and Querying of Connection Properties 1122 At any point, the application can set and query the properties of a 1123 Connection. Depending on the phase the Connection is in, the 1124 Connection properties will include different information. 1126 ConnectionProperties := Connection.GetProperties() 1128 Connection.SetProperties() 1130 Connection properties include: 1132 o The status of the Connection, which can be one of the following: 1133 Establishing, Established, Closing, or Closed. 1135 o Transport Features of the protocols that conform to the Required 1136 and Prohibited Transport Preferences, which might be selected by 1137 the transport system during Establishment. These features 1138 correspond to the properties given in Section 5.2 and can only be 1139 queried. 1141 o Transport Features of the Protocol Stacks that were selected and 1142 instantiated, once the Connection has been established. These 1143 features correspond to the properties given in Section 5.2 and can 1144 only be queried. Instead of preference levels, these features 1145 have boolean values indicating whether or not they were selected. 1146 Note that these transport features may not fully reflect the 1147 specified parameters given in the pre-establishment phase. For 1148 example, a certain Protocol Selection Property that an application 1149 specified as Preferred may not actually be present in the chosen 1150 Protocol Stack Instances because none of the currently available 1151 transport protocols had this feature. 1153 o Protocol Properties of the Protocol Stack in use (see Section 9.1 1154 below). These can be set or queried. Certain specific procotol 1155 queries may be read-only, on a protocol- and property-specific 1156 basis. 1158 o Path Properties of the path(s) in use, once the Connection has 1159 been established. These properties can be derived from the local 1160 provisioning domain, measurements by the Protocol Stack, or other 1161 sources. They can only be queried. 1163 9.1. Protocol Properties 1165 Protocol Properties represent the configuration of the selected 1166 Protocol Stacks backing a Connection. Some properties apply 1167 generically across multiple transport protocols, while other 1168 properties only apply to specific protocols. The default settings of 1169 these properties will vary based on the specific protocols being used 1170 and the system's configuration. 1172 Note that Protocol Properties are also set during pre-establishment, 1173 as transport parameters, to preconfigure Protocol Stacks during 1174 establishment. 1176 Generic Protocol Properties include: 1178 o Relative niceness: This numeric property is similar to the 1179 Niceness send property (see Section 7.1.2), a non-negative integer 1180 representing the relative inverse priority of this Connection 1181 relative to other Connections in the same Connection Group. It 1182 has no effect on Connections not part of a Connection Group. As 1183 noted in Section 6.4, this property is not entangled when 1184 Connections are cloned. 1186 o Timeout for aborting Connection: This numeric property specifies 1187 how long to wait before aborting a Connection during 1188 establishment, or before deciding that a Connection has failed 1189 after establishment. It is given in seconds. 1191 o Retransmission threshold before excessive retransmission 1192 notification: This numeric property specifies after how many 1193 retransmissions to inform the application about "Excessive 1194 Retransmissions". 1196 o Required minimum coverage of the checksum for receiving: This 1197 numeric property specifies the part of the received data that 1198 needs to be covered by a checksum. It is given in Bytes. A value 1199 of 0 means that no checksum is required, and a special value 1200 (e.g., -1) indicates full checksum coverage. 1202 o Connection group transmission scheduler: This enumerated property 1203 specifies which scheduler should be used among Connections within 1204 a Connection Group. It applies to Connection Groups; the set of 1205 schedulers can be taken from [I-D.ietf-tsvwg-sctp-ndata]. 1207 o Maximum message size concurrent with Connection establishment: 1208 This numeric property represents the maximum Message size that can 1209 be sent before or during Connection establishment, see also 1210 Section 7.1.4. It is given in Bytes. This property is read-only. 1212 o Maximum Message size before fragmentation or segmentation: This 1213 numeric property, if applicable, represents the maximum Message 1214 size that can be sent without incurring network-layer 1215 fragmentation and/or transport layer segmentation at the sender. 1216 This property is read-only. 1218 o Maximum Message size on send: This numeric property represents the 1219 maximum Message size that can be sent. This property is read- 1220 only. 1222 o Maximum Message size on receive: This numeric property represents 1223 the maximum Message size that can be received. This property is 1224 read-only. 1226 In order to specify Specific Protocol Properties, Transport System 1227 implementations may offer applications to attach a set of options to 1228 the Preconnection Object, associated with a specific protocol. For 1229 example, an application could specify a set of TCP Options to use if 1230 and only if TCP is selected by the system. Such properties must not 1231 be assumed to apply across different protocols. Attempts to set 1232 specific protocol properties on a Protocol Stack not containing that 1233 specific protocol are simply ignored, and do not raise an error. 1235 10. Connection Termination 1237 Close terminates a Connection after satisfying all the requirements 1238 that were specified regarding the delivery of Messages that the 1239 application has already given to the transport system. For example, 1240 if reliable delivery was requested for a Message handed over before 1241 calling Close, the transport system will ensure that this Message is 1242 indeed delivered. If the Remote Endpoint still has data to send, it 1243 cannot be received after this call. 1245 Connection.Close() 1247 The Closed Event can inform the application that the Remote Endpoint 1248 has closed the Connection; however, there is no guarantee that a 1249 remote close will be signaled. 1251 Connection -> Closed<> 1253 Abort terminates a Connection without delivering remaining data: 1255 Connection.Abort() 1257 A ConnectionError can inform the application that the other side has 1258 aborted the Connection; however, there is no guarantee that an abort 1259 will be signaled: 1261 Connection -> ConnectionError<> 1263 11. IANA Considerations 1265 RFC-EDITOR: Please remove this section before publication. 1267 This document has no Actions for IANA. 1269 12. Security Considerations 1271 This document describes a generic API for interacting with a 1272 transport services (TAPS) system. Part of this API includes 1273 configuration details for transport security protocols, as discussed 1274 in Section Section 5.3. It does not recommend use (or disuse) of 1275 specific algorithms or protocols. Any API-compatible transport 1276 security protocol should work in a TAPS system. 1278 13. Acknowledgements 1280 This work has received funding from the European Union's Horizon 2020 1281 research and innovation programme under grant agreements No. 644334 1282 (NEAT) and No. 688421 (MAMI). 1284 This work has been supported by Leibniz Prize project funds of DFG - 1285 German Research Foundation: Gottfried Wilhelm Leibniz-Preis 2011 (FKZ 1286 FE 570/4-1). 1288 This work has been supported by the UK Engineering and Physical 1289 Sciences Research Council under grant EP/R04144X/1. 1291 Thanks to Stuart Cheshire, Josh Graessley, David Schinazi, and Eric 1292 Kinnear for their implementation and design efforts, including Happy 1293 Eyeballs, that heavily influenced this work. Thanks to Laurent Chuat 1294 and Jason Lee for initial work on the Post Sockets interface, from 1295 which this work has evolved. 1297 14. References 1299 14.1. Normative References 1301 [I-D.ietf-taps-minset] 1302 Welzl, M. and S. Gjessing, "A Minimal Set of Transport 1303 Services for TAPS Systems", draft-ietf-taps-minset-02 1304 (work in progress), February 2018. 1306 [I-D.ietf-tsvwg-rtcweb-qos] 1307 Jones, P., Dhesikan, S., Jennings, C., and D. Druta, "DSCP 1308 Packet Markings for WebRTC QoS", draft-ietf-tsvwg-rtcweb- 1309 qos-18 (work in progress), August 2016. 1311 [I-D.ietf-tsvwg-sctp-ndata] 1312 Stewart, R., Tuexen, M., Loreto, S., and R. Seggelmann, 1313 "Stream Schedulers and User Message Interleaving for the 1314 Stream Control Transmission Protocol", draft-ietf-tsvwg- 1315 sctp-ndata-13 (work in progress), September 2017. 1317 [TAPS-ARCH] 1318 Pauly, T., Ed., Trammell, B., Ed., Brunstrom, A., 1319 Fairhurst, G., Perkins, C., Tiesel, P., and C. Wood, "An 1320 Architecture for Transport Services", n.d.. 1322 14.2. Informative References 1324 [I-D.pauly-taps-transport-security] 1325 Pauly, T., Rose, K., and C. Wood, "A Survey of Transport 1326 Security Protocols", draft-pauly-taps-transport- 1327 security-01 (work in progress), January 2018. 1329 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 1330 RFC 793, DOI 10.17487/RFC0793, September 1981, 1331 . 1333 [RFC5245] Rosenberg, J., "Interactive Connectivity Establishment 1334 (ICE): A Protocol for Network Address Translator (NAT) 1335 Traversal for Offer/Answer Protocols", RFC 5245, 1336 DOI 10.17487/RFC5245, April 2010, 1337 . 1339 [RFC8084] Fairhurst, G., "Network Transport Circuit Breakers", 1340 BCP 208, RFC 8084, DOI 10.17487/RFC8084, March 2017, 1341 . 1343 [RFC8095] Fairhurst, G., Ed., Trammell, B., Ed., and M. Kuehlewind, 1344 Ed., "Services Provided by IETF Transport Protocols and 1345 Congestion Control Mechanisms", RFC 8095, 1346 DOI 10.17487/RFC8095, March 2017, 1347 . 1349 Appendix A. Additional Properties 1351 The interface specified by this document represents the minimal 1352 common interface to an endpoint in the transport services 1353 architecture [TAPS-ARCH], based upon that architecture and on the 1354 minimal set of transport service features elaborated in 1355 [I-D.ietf-taps-minset]. However, the interface has been designed 1356 with extension points to allow the implementation of features beyond 1357 those in the minimal common interface: Protocol Selection Properties, 1358 Path Selection Properties, and options on Message send are open sets. 1359 Implementations of the interface are free to extend these sets to 1360 provide additional expressiveness to applications written on top of 1361 them. 1363 This appendix enumerates a few additional parameters and properties 1364 that could be used to enhance transport protocol and/or path 1365 selection, or the transmission of messages given a Protocol Stack 1366 that implements them. These are not part of the interface, and may 1367 be removed from the final document, but are presented here to support 1368 discussion within the TAPS working group as to whether they should be 1369 added to a future revision of the base specification. 1371 A.1. Protocol and Path Selection Properties 1373 The following protocol and path selection properties might be made 1374 available in addition to those specified in Section 5.2: 1376 o Suggest a timeout to the Remote Endpoint: This boolean property 1377 specifies whether an application considers it useful to propose a 1378 timeout until the Connection is assumed to be lost. This property 1379 applies to Connections and Connection Groups. This is not a 1380 strict requirement. The default is to have this option. 1382 [EDITOR'S NOTE: For discussion of this option, see 1383 https://github.com/taps-api/drafts/issues/109] 1385 o Request not to delay acknowledgment of Message: This boolean 1386 property specifies whether an application considers it useful to 1387 request for Message that its acknowledgment be sent out as early 1388 as possible instead of potentially being bundled with other 1389 acknowledgments. This property applies to Connections and 1390 Connection groups. This is not a strict requirement. The default 1391 is to not have this option. [EDITOR'S NOTE: For discussion of 1392 this option, see https://github.com/taps-api/drafts/issues/90] 1394 A.1.1. Application Intents 1396 Application Intents are a group of transport properties expressing 1397 what an application wants to achieve, knows, assumes or prefers 1398 regarding its communication. They are not strict requirements. In 1399 particular, they should not be used to express any Quality of Service 1400 expectations that an application might have. Instead, an application 1401 should express its intentions and its expected traffic 1402 characteristics in order to help the transport system make decisions 1403 that best match it, but on a best-effort basis. Even though 1404 Application Intents do not represent Quality of Service requirements, 1405 a transport system may use them to determine a DSCP value, e.g. 1406 similar to Table 1 in [I-D.ietf-tsvwg-rtcweb-qos]. 1408 Application Intents can influence protocol selection, protocol 1409 configuration, path selection, and endpoint selection. For example, 1410 setting the "Timeliness" Intent to "Interactive" may lead the 1411 transport system to disable the Nagle algorithm for a Connection, 1412 while setting the "Timeliness" to "Background" may lead it to setting 1413 the DSCP value to "scavenger". If the "Size to be Sent" Intent is 1414 set on an individual Message, it may influence path selection. 1416 Specifying Application Intents is not mandatory. An application can 1417 specify any combination of Application Intents. If specified, 1418 Application Intents are defined as parameters passed to the 1419 Preconnection Object, and may influence the Connection established 1420 from that Preconnection. If a Connection is cloned to form a 1421 Connection Group, and associated Application Intents are cloned along 1422 with the other transport parameters. Some Intents have also 1423 corresponding Message Properties, similar to the properties in 1424 Section 7.1. 1426 Application Intents can be added to this interface as Transport 1427 Preferences with the "Prefer" preference level. 1429 A.1.1.1. Traffic Category 1431 This Intent specifies what the application expect the dominating 1432 traffic pattern to be. 1434 Possible Category values are: 1436 Query: Single request / response style workload, latency bound 1438 Control: Long lasting low bandwidth control channel, not bandwidth 1439 bound 1441 Stream: Stream of data with steady data rate 1443 Bulk: Bulk transfer of large Messages, presumably bandwidth bound 1445 The default is to not assume any particular traffic pattern. Most 1446 categories suggest the use of other intents to further describe the 1447 traffic pattern anticipated, e.g., the bulk category suggesting the 1448 use of the Message Size intents or the stream category suggesting the 1449 Stream Bitrate and Duration intents. 1451 A.1.1.2. Size to be Sent / Received 1453 This Intent specifies what the application expects the size of a 1454 transfer to be. It is a numeric property and given in Bytes. 1456 A.1.1.3. Duration 1458 This Intent specifies what the application expects the lifetime of a 1459 transfer to be. It is a numeric property and given in milliseconds. 1461 A.1.1.4. Send / Receive Bit-rate 1463 This Intent specifies what the application expects the bit-rate of a 1464 transfer to be. It is a numeric property and given in Bytes per 1465 second. 1467 A.1.1.5. Cost Preferences 1469 This Intent describes what an application prefers regarding monetary 1470 costs, e.g., whether it considers it acceptable to utilize limited 1471 data volume. It provides hints to the transport system on how to 1472 handle trade-offs between cost and performance or reliability. This 1473 Intent can also apply to an individual Messages. 1475 No Expense: Avoid transports associated with monetary cost 1476 Optimize Cost: Prefer inexpensive transports and accept service 1477 degradation 1479 Balance Cost: Use system policy to balance cost and other criteria 1481 Ignore Cost: Ignore cost, choose transport solely based on other 1482 criteria 1484 The default is "Balance Cost". 1486 A.2. Protocol Properties 1488 The following protocol properties might be made available in addition 1489 to those in Section 9.1: 1491 o Abort timeout to suggest to the Remote Endpoint: This numeric 1492 property specifies the timeout to propose to the Remote Endpoint. 1493 It is given in seconds. [EDITOR'S NOTE: For discussion of this 1494 property, see https://github.com/taps-api/drafts/issues/109] 1496 A.3. Send Parameters 1498 The following send parameters might be made available in addition to 1499 those specified in Section 7.1: 1501 o Immediate: Immediate is a boolean property. If true, the caller 1502 prefers immediacy to efficient capacity usage for this Message. 1503 For example, this means that the Message should not be bundled 1504 with other Message into the same transmission by the underlying 1505 Protocol Stack. 1507 o Send Bitrate: This numeric property in Bytes per second specifies 1508 at what bitrate the application wishes the Message to be sent. A 1509 transport supporting this feature will not exceed the requested 1510 Send Bitrate even if flow-control and congestion control allow 1511 higher bitrates. This helps to avid bursty traffic pattern on 1512 busy video streaming servers. 1514 Appendix B. Sample API definition in Go 1516 This document defines an abstract interface. To illustrate how this 1517 would map concretely into a programming language, an API interface 1518 definition in Go is available online at https://github.com/mami- 1519 project/postsocket. Documentation for this API - an illustration of 1520 the documentation an application developer would see for an instance 1521 of this interface - is available online at 1522 https://godoc.org/github.com/mami-project/postsocket. This API 1523 definition will be kept largely in sync with the development of this 1524 abstract interface definition. 1526 Authors' Addresses 1528 Brian Trammell (editor) 1529 ETH Zurich 1530 Gloriastrasse 35 1531 8092 Zurich 1532 Switzerland 1534 Email: ietf@trammell.ch 1536 Michael Welzl (editor) 1537 University of Oslo 1538 PO Box 1080 Blindern 1539 0316 Oslo 1540 Norway 1542 Email: michawe@ifi.uio.no 1544 Theresa Enghardt 1545 TU Berlin 1546 Marchstrasse 23 1547 10587 Berlin 1548 Germany 1550 Email: theresa@inet.tu-berlin.de 1552 Godred Fairhurst 1553 University of Aberdeen 1554 Fraser Noble Building 1555 Aberdeen, AB24 3UE 1556 Scotland 1558 Email: gorry@erg.abdn.ac.uk 1559 URI: http://www.erg.abdn.ac.uk/ 1560 Mirja Kuehlewind 1561 ETH Zurich 1562 Gloriastrasse 35 1563 8092 Zurich 1564 Switzerland 1566 Email: mirja.kuehlewind@tik.ee.ethz.ch 1568 Colin Perkins 1569 University of Glasgow 1570 School of Computing Science 1571 Glasgow G12 8QQ 1572 United Kingdom 1574 Email: csp@csperkins.org 1576 Philipp S. Tiesel 1577 TU Berlin 1578 Marchstrasse 23 1579 10587 Berlin 1580 Germany 1582 Email: philipp@inet.tu-berlin.de 1584 Chris Wood 1585 Apple Inc. 1586 1 Infinite Loop 1587 Cupertino, California 95014 1588 United States of America 1590 Email: cawood@apple.com