| RFC 9622 | Transport Services API | January 2025 |
| Trammell, et al. | Standards Track | [Page] |
This document describes an abstract Application Programming Interface (API) to the transportlayer that enables the selection of transport protocols andnetwork paths dynamically at runtime. This API enables faster deploymentof new protocols and protocol features without requiring changes to theapplications. The specified API follows the Transport Services Architectureby providing asynchronous, atomic transmission of Messages. It is intended to replace theBSD Socket API as the common interface to thetransport layer, in an environment where endpoints could select frommultiple network paths and potential transport protocols.¶
This is an Internet Standards Track document.¶
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.¶
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained athttps://www.rfc-editor.org/info/rfc9622.¶
Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
This document specifies an abstract Application Programming Interface (API) that describes the interface component ofthe high-level Transport Services Architecture defined in[RFC9621]. A Transport Services System supportsasynchronous, atomic transmission of Messages over transport protocols andnetwork paths dynamically selected at runtime, in environments where an endpointselects from multiple network paths and potential transport protocols.¶
Applications that adopt this API will benefit from a wide set oftransport features that can evolve over time. This protocol-independent API ensures that the systemproviding the API can optimize its behavior based on the applicationrequirements and network conditions, without requiring changes to theapplications. This flexibility enables faster deployment of new features andprotocols and can support applications by offering racing and fallbackmechanisms, which otherwise need to be separately implemented in each application.Transport Services Implementations are free to take any desired form as longas the API specification in this document is honored; a non-prescriptive guide toimplementing a Transport Services System is available (see[RFC9623]).¶
The Transport Services System derives specific path and Protocol SelectionProperties and supported transport features from the analysis provided in[RFC8095],[RFC8923], and[RFC8922]. The Transport Services API enables an implementationto dynamically choose a transport protocol ratherthan statically binding applications to a protocol atcompile time. The Transport Services API also providesapplications with a way to override transport selection and instantiate a specific stack,e.g., to support servers wishing to listen to a specific protocol. However, forcing achoice to use a specific Protocol Stack is discouraged for general use because it can reduce portability.¶
The Transport Services API is described in terms of:¶
Objects with which an application can interact;¶
Actions the application can perform on these objects;¶
Events, which an object can send to an application to be processed asynchronously; and¶
Parameters associated with these actions and events.¶
The following notations, which can be combined, are used in this document:¶
An action that creates an object:¶
Object := Action()¶
An action that creates an array of objects:¶
[]Object := Action()¶
An action that is performed on an object:¶
Object.Action()¶
An object sends an event:¶
Object -> Event<>¶
An action takes a set of parameters; an event contains a set of parameters.Action and event parameters whose names are suffixed with a question mark are optional:¶
Action(param0, param1?, ...) Event<param0, param1?, ...>¶
Objects that are passed as parameters to actions use call-by-value behavior.Actions not associated with an object are actions on the API; they are equivalent to actions on a per-application global context.¶
Events are sent to the application or application-supplied code (e.g., Framers;seeSection 9.1.2) for processing; the details of event interfaces are specific to the platform orimplementation and can be implemented usingother forms of asynchronous processing, as idiomatic for theimplementing platform.¶
We also make use of the following basic types:¶
true orfalse.¶(Enumeration, Preference).Instances take a sequence of values, each valid for the corresponding valuetype.¶[]Type, an instance takes a value for each of zero or moreelements in a sequence of the given Type. An array can be of fixed orvariable length.¶For guidance on how these abstract concepts can be implemented in languagesin accordance with language-specific design patterns and platform features,seeAppendix A.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14[RFC2119][RFC8174] when, and only when, they appear in all capitals, as shown here.¶
The design of the API specified in this document is based on a set ofprinciples, themselves an elaboration on the architectural design principlesdefined in[RFC9621]. The API defined in this documentprovides:¶
A Transport Services System thatcan offer a variety of transport protocols, independentof the Protocol Stacks that will be used atruntime. To the degree possible, all common features of these ProtocolStacks are made available to the application in atransport-independent way.This enables applications written for a single APIto make use of transport protocols in terms of the featuresthey provide.¶
A unified API to datagram and stream-oriented transports, allowingthe use of a common API for Connection establishment and closing.¶
Message-orientation, as opposed to stream-orientation, using application-assisted framing and deframing where the underlying transport does not itself provide the required framing.¶
Asynchronous Connection establishment, transmission, and reception.This allows concurrent operations during establishment and event-drivenapplication interactions with the transport layer.¶
Selection between alternate network paths, using additional information about thenetworks over which a Connection can operate (e.g., Provisioning Domain (PvD)information[RFC7556]) where available.¶
Explicit support for transport-specific features to be applied, when thatparticular transport is part of a chosen Protocol Stack.¶
Explicit support for security properties as first-order transport features.¶
Explicit support for configuration of cryptographic identities and transportSecurity Parameters persistent across multiple Connections.¶
Explicit support for multistreaming and multipath transport protocols, andthe grouping of related Connections into Connection Groups through "cloning"of Connections (seeSection 7.4). This function allows applications to take full advantage of newtransport protocols supporting these features.¶
An application primarily interacts with this API through two objects:Preconnections and Connections. A Preconnection object (Section 6)represents a set of Properties and constraints on the selection and configuration ofpaths and protocols to establish a Connection with an Endpoint. A Connection objectrepresents an instance of a transport Protocol Stack on which data can be sent to and/orreceived from a Remote Endpoint (i.e., a logical connection that, depending on thekind of transport, can be bidirectional or unidirectional, and that can use a streamprotocol or a datagram protocol). Connections are presented consistently to theapplication, irrespective of whether the underlying transport is connectionless orconnection oriented. Connections can be created from Preconnections in three ways:¶
initiating the Preconnection (i.e., creating a Connection from the Preconnection, actively opening, as in a client; seeInitiate inSection 7.1),¶
listening on the Preconnection (i.e., creating a Listener based on the Preconnection, passively opening, as in a server; seeListen inSection 7.2), or¶
a rendezvous for the Preconnection (i.e., peer-to-peer Connection establishment; seeRendezvous inSection 7.3).¶
Once a Connection is established, data can be sent and received on it in the form ofMessages. The API supports the preservation of Message boundaries via bothexplicit Protocol Stack support and application support through aMessage Framer that finds Message boundaries in a stream. Messages arereceived asynchronously through event handlers registered by the application.Errors and other notifications also happen asynchronously on the Connection.It is not necessary for an application to handle all events; some events canhave implementation-specific default handlers.¶
The applicationSHOULD NOTassume that ignoring events (e.g., errors) is always safe.¶
The following usage examples illustrate how an application might use theTransport Services API to act as:¶
a server, by listening for incoming Connections, receiving requests,and sending responses; seeSection 3.1.1.¶
a client, by connecting to a Remote Endpoint usingInitiate, sendingrequests, and receiving responses; seeSection 3.1.2.¶
a peer, by connecting to a Remote Endpoint usingRendezvous whilesimultaneously waiting for incoming Connections, sending Messages, andreceiving Messages; seeSection 3.1.3.¶
The examples in this section presume that a transport protocol is availablebetween the Local and Remote Endpoints and that this protocol provides reliable data transfer, preservation ofdata ordering, and preservation of Message boundaries. In this case, theapplication can choose to receive only complete Messages.¶
If none of the available transport protocols provide preservation of Messageboundaries, but there is a transport protocol that provides a reliable orderedbyte-stream, an application could receive this byte-stream as partialMessages and transform it into application-layer Messages. Alternatively,an application might provide a Message Framer, which can transform asequence of Messages into a byte-stream and vice versa (Section 9.1.2).¶
This is an example of how an application might listen for incoming Connectionsusing the Transport Services API, receive a request, and send a response.¶
LocalSpecifier := NewLocalEndpoint()LocalSpecifier.WithInterface("any")LocalSpecifier.WithService("https")TransportProperties := NewTransportProperties()TransportProperties.Require(preserveMsgBoundaries)// Reliable data transfer and preserve order are required by defaultSecurityParameters := NewSecurityParameters()SecurityParameters.Set(serverCertificate, myCertificate)// Specifying a Remote Endpoint is optional when using ListenPreconnection := NewPreconnection(LocalSpecifier, TransportProperties, SecurityParameters)Listener := Preconnection.Listen()Listener -> ConnectionReceived<Connection>// Only receive complete messages in a Conn.Received handlerConnection.Receive()Connection -> Received<messageDataRequest, messageContext>//---- Receive event handler begin ----Connection.Send(messageDataResponse)Connection.Close()// Stop listening for incoming Connections// (this example supports only one Connection)Listener.Stop()//---- Receive event handler end ----¶This is an example of how an application might open two Connections to a remote application using the Transport Services API, send a request, and receive a response for each of the two Connections.The code designated with comments as "Ready event handler" could, for example, be implementedas a callback function. This function would receive the Connection that it expectsto operate on ("Connection" and "Connection2" in the example) handed over using the variablename "C".¶
RemoteSpecifier := NewRemoteEndpoint()RemoteSpecifier.WithHostName("example.com")RemoteSpecifier.WithService("https")TransportProperties := NewTransportProperties()TransportProperties.Require(preserve-msg-boundaries)// Reliable data transfer and preserve order are required by defaultSecurityParameters := NewSecurityParameters()TrustCallback := NewCallback({ // Verify the identity of the Remote Endpoint and return the result})SecurityParameters.SetTrustVerificationCallback(TrustCallback)// Specifying a Local Endpoint is optional when using InitiatePreconnection := NewPreconnection(RemoteSpecifier, TransportProperties, SecurityParameters)Connection := Preconnection.Initiate()Connection2 := Connection.Clone()Connection -> Ready<>Connection2 -> Ready<>//---- Ready event handler for any Connection C begin ----C.Send(messageDataRequest)// Only receive complete messagesC.Receive()//---- Ready event handler for any Connection C end ----Connection -> Received<messageDataResponse, messageContext>Connection2 -> Received<messageDataResponse, messageContext>// Close the Connection in a Receive event handlerConnection.Close()Connection2.Close()¶A Preconnection serves as a template for creating a Connection via initiating, listening, or via rendezvous. Once a Connection has been created,changes made to the Preconnection that was used to create it do not affect this Connection. Preconnections are reusable after being used to create a Connection, whether or not this Connection was closed. Hence, in the above example, it would be correct for the client to initiate a third Connection to theexample.com server by continuing as follows:¶
//.. carry out adjustments to the Preconnection, if desiredConnection3 := Preconnection.Initiate()¶
This is an example of how an application might establish a Connection with apeer usingRendezvous, send a Message, and receive a Message.¶
// Configure local candidates: a port on the Local Endpoint// and via a Session Traversal Utilities for NAT (STUN) serverHostCandidate := NewLocalEndpoint()HostCandidate.WithPort(9876)StunCandidate := NewLocalEndpoint()StunCandidate.WithStunServer(address, port, credentials)LocalCandidates = [HostCandidate, StunCandidate]TransportProperties := // ...Configure transport propertiesSecurityParameters := // ...Configure security propertiesPreconnection := NewPreconnection(LocalCandidates, [], // No remote candidates yet TransportProperties, SecurityParameters)// Resolve the LocalCandidates. The Preconnection.Resolve()// call resolves both local and remote candidates; however,// because the remote candidates have not yet been specified,// the ResolvedRemote list returned will be empty and is not// used.ResolvedLocal, ResolvedRemote = Preconnection.Resolve()// Application-specific code goes here to send the ResolvedLocal// list to the peer via some out-of-band signaling channel (e.g.,// in a SIP message)....// Application-specific code goes here to receive RemoteCandidates// (type []RemoteEndpoint, a list of RemoteEndpoint objects) from// the peer via the signaling channel....// Add remote candidates and initiate the rendezvous:Preconnection.AddRemote(RemoteCandidates)Preconnection.Rendezvous()Preconnection -> RendezvousDone<Connection>//---- RendezvousDone event handler begin ----Connection.Send(messageDataRequest)Connection.Receive()//---- RendezvousDone event handler end ----Connection -> Received<messageDataResponse, messageContext>// If new Remote Endpoint candidates are received from the// peer over the signaling channel -- for example, if using// Trickle Interactive Connectivity Establishment (ICE) --// then add them to the Connection:Connection.AddRemote(NewRemoteCandidates)// On a PathChange event, resolve the Local Endpoint Identifiers to// see if a new Local Endpoint has become available and, if// so, send to the peer as a new candidate and add to the// Connection:Connection -> PathChange<>//---- PathChange event handler begin ----ResolvedLocal, ResolvedRemote = Preconnection.Resolve()if ResolvedLocal has changed: // Application-specific code goes here to send the // ResolvedLocal list to the peer via the signaling channel ... // Add the new Local Endpoints to the Connection: Connection.AddLocal(ResolvedLocal)//---- PathChange event handler end ----// Close the Connection in a Receive event handler:Connection.Close()¶
Each application using the Transport Services API declares its preferencesfor how the Transport Services System is to operate. This is done by usingTransport Properties, as defined in[RFC9621], at each stageof the lifetime of a Connection.¶
Transport Properties are divided into Selection, Connection, and MessageProperties.¶
Selection Properties (seeSection 6.2) can only be setduring preestablishment. They are only used to specify which paths andProtocol Stacks can be used and are preferred by the application.CallingInitiate on a Preconnection creates an outbound Connection,and the Selection Properties remain readable from theConnection but become immutable. Selection Propertiescan be set on Preconnections, and the effect of Selection Propertiescan be queried on Connections and Messages.¶
Connection Properties (seeSection 8.1) are used to informdecisions made during establishment and to fine-tune the establishedConnection. They can be set during preestablishment and can bechanged later. Connection Properties can be set on Connections andPreconnections; when set on Preconnections, they act as an initialdefault for the resulting Connections.¶
Message Properties (seeSection 9.1.3) control the behavior of theselected Protocol Stack(s) when sending Messages. Message Propertiescan be set on Messages, Connections, and Preconnections; when set onthe latter two, they act as an initial default for the Messages sentover those Connections.¶
Note that configuring Connection Properties and Message Properties onPreconnections is preferred over setting them later. Early specification ofConnection Properties allows their use as additional input to the selectionprocess. Protocol-specific Properties, which enable configuration of specializedfeatures of a specific protocol (seeSection 3.2 of [RFC9621]), are notused as input to the selection process; they only support configuration ifthe respective protocol has been selected.¶
Transport Properties are referred to by names, represented as case-insensitive strings. These names serve two purposes:¶
Allowing different components of a Transport Services Implementation to pass Transport Properties (e.g., between a language frontend and a policy manager) or to enable a Transport Services Implementation to represent Properties retrieved from a file or other storage to the application.¶
Making the code of different Transport Services Implementations look similar. While individual programming languages might preclude strict adherence to the naming convention of representing Property names as case-insensitive strings (for instance, by prohibiting the use of hyphens in symbols), users interacting with multiple implementations will still benefit from the consistency resulting from the use of visually similar symbols.¶
Transport Property names are hierarchically organized in theform [<Namespace>.]<PropertyName>.¶
The optional Namespace component and its trailing dot character (".")MUST be omitted for well-knowngeneric Properties, i.e., for Properties that are not specific to a protocol.¶
Protocol-specific PropertiesMUST use the protocol acronym as the Namespace (e.g., aConnection that uses TCP could support a TCP-specific Transport Property, such as the TCP User Timeoutvalue, in a Protocol-specific Property calledtcp.userTimeoutValue (seeSection 8.2)).¶
Vendor-specific or implementation-specific PropertiesMUST be placed in a Namespace starting with the underscore character ("_") andSHOULD use a string identifying the vendor or implementation.¶
For IETF protocols, the name of a Protocol-specific PropertyMUST be specified in an RFC from the IETF Stream (after IETF Review[RFC8126]). An IETF protocol Namespace does not start with an underscore character ("_").¶
Namespaces for each of the keywords provided in the "Protocol Numbers" registry(see<https://www.iana.org/assignments/protocol-numbers/>) are reservedfor Protocol-specific Properties andMUST NOT be used for vendor-specific or implementation-specific Properties.Terms listed as keywords, as in the "Protocol Numbers" registry,SHOULD be avoided as any part of a vendor-specific orimplementation-specific Property name.¶
Though Transport Property names are case insensitive, it is recommended to use camelCase to improve readability.Implementations may transpose Transport Property names into snake_case or PascalCase to blend into the language environment.¶
Each Transport Property has one of the basic types described inSection 1.1.¶
Most Selection Properties (seeSection 6.2) are of the Enumeration type,and they use the Preference Enumeration, which takes one of five possible values(Prohibit,Avoid,No Preference,Prefer, orRequire) denoting the level of preferencefor a given Property during protocol selection.¶
This document defines a language- and platform-independent API of aTransport Services System. Given the wide variety of languages and languageconventions used to write applications that use the transport layer to connectto other applications over the Internet, this independence makes this APInecessarily abstract.¶
There is no interoperability benefit in tightly defining how the API ispresented to application programmers across diverse platforms. However,maintaining the "shape" of the abstract API across different platforms reducesthe effort for programmers who learn to use the Transport Services API to thenapply their knowledge to another platform. That said, implementations havesignificant freedom in presenting this API to programmers, balancing theconventions of the protocol with the shape of the API. We make the followingrecommendations:¶
Actions, events, and errors in implementations of the Transport Services APISHOULD usethe names assigned to them in this document, subject to capitalization,punctuation, and other typographic conventions in the language of theimplementation, unless the implementation itself uses different names forsubstantially equivalent objects for networking by convention.¶
Transport Services SystemsSHOULD implement each Selection Property,Connection Property, and MessageContext Property specified in this document.These featuresSHOULD be implemented even when, in a specific implementation, itwill always result in no operation, e.g., there is no action when the APIspecifies a Property that is not available in a transport protocol implementedon a specific platform. For example, if TCP is the only underlying transport protocol,the Message PropertymsgOrdered can be implemented (trivially, as a no-op) asdisabling the requirement for ordering will not have any effect on delivery orderfor Connections over TCP. Similarly, themsgLifetime Message Property can beimplemented but ignored, as the description of this Property (Section 9.1.3.1) states that "it is notguaranteed that a Message will not be sent when its Lifetime has expired".¶
Implementations can use other representations for Transport Property names,e.g., by providing constants, but should provide a straightforward mappingbetween their representation and the Property names specified here.¶
The preestablishment phase allows applications to specify Properties forthe Connections that they are about to make or to query the API about potentialConnections they could make.¶
A Preconnection object represents a potential Connection. It is a passive object(a data structure) that merely maintains the state thatdescribes the Properties of a Connection that might exist in the future. This statecomprises Local Endpoint and Remote Endpoint objects that denote the Endpointsof the potential Connection (seeSection 6.1), the Selection Properties(seeSection 6.2), any preconfigured Connection Properties(Section 8.1), and the Security Parameters (seeSection 6.3):¶
Preconnection := NewPreconnection([]LocalEndpoint, []RemoteEndpoint, TransportProperties, SecurityParameters)¶
At least one Local EndpointMUST be specified if the Preconnection is used toListenfor incoming Connections, but the list of Local EndpointsMAY be empty ifthe Preconnection is used toInitiateconnections. If no Local Endpoint is specified, the Transport Services System willassign an ephemeral local port to the Connection on the appropriate interface(s).At least one Remote EndpointMUST be specified if the Preconnection is usedtoInitiate Connections, but the list of Remote EndpointsMAY be empty ifthe Preconnection is used toListen for incoming Connections.At least one Local Endpoint and one Remote EndpointMUST be specified if apeer-to-peerRendezvous is to occur based on the Preconnection.¶
If more than one Local Endpoint is specified on a Preconnection, then the application is indicating that all of the Local Endpoints are eligible to be used for Connections. For example, their Endpoint Identifiers might correspond to different interfaces on a multihomedhost or their Endpoint Identifiers might correspond to local interfaces and a STUN server thatcan be resolved to a server-reflexive address for a Preconnection used tomake a peer-to-peerRendezvous.¶
If more than one Remote Endpoint is specified on the Preconnection, theapplication is indicating that it expects all of the Remote Endpoints tooffer an equivalent service and that the Transport Services System can chooseany of them for a Connection.For example, a Remote Endpoint might represent various networkinterfaces of a host, or a server-reflexive address that can be used toreach a host, or a set of hosts that provide equivalent local balancedservice.¶
In most cases, it is expected that a single Remote Endpoint will bespecified by name, and a later call toInitiate on the Preconnection(seeSection 7.1) will internally resolve that name to a list of concreteEndpoint Identifiers. Specifying multiple Remote Endpoints on a Preconnection allowsapplications to override this for more detailed control.¶
If Message Framers are used (seeSection 9.1.2), theyMUST be added to thePreconnection during preestablishment.¶
The Transport Services API uses the Local Endpoint and Remote Endpoint objectsto refer to the Endpoints of a Connection. Endpoints can be createdas either remote or local:¶
RemoteSpecifier := NewRemoteEndpoint()LocalSpecifier := NewLocalEndpoint()¶
A single Endpoint object represents the identity of a network host. That Endpointcan be more or less specific, depending on which Endpoint Identifiers are set. For example,an Endpoint that only specifies a hostname can, in fact, finally correspondto several different IP addresses on different hosts.¶
An Endpoint object can be configured with the following identifiers:¶
HostName (string):¶
RemoteSpecifier.WithHostName("example.com")¶Port (a 16-bit unsigned Integer):¶
RemoteSpecifier.WithPort(443)¶
Service (an identifier string that maps to a port; either a servicename associated with a port number (from<https://www.iana.org/assignments/service-names-port-numbers/>) or a DNS SRV service name to be resolved):¶
RemoteSpecifier.WithService("https")¶IP address (an IPv4 or IPv6 address type; note that the examples here show the human-readable form of the IP addresses, but the functions can take a binary encoding of the addresses):¶
RemoteSpecifier.WithIPAddress(192.0.2.21)¶
RemoteSpecifier.WithIPAddress(2001:db8:4920:e29d:a420:7461:7073:a)¶
Interface identifier (which can be a string name or other platform-specific identifier), e.g., to qualify link-local addresses (seeSection 6.1.2 for details):¶
LocalSpecifier.WithInterface("en0")¶TheResolve action on a Preconnection can be used to obtain a list ofavailable local interfaces.¶
Note that an IPv6 address specified with a scope zone ID (e.g.,fe80::2001:db8%en0)is equivalent toWithIPAddress with an unscoped address andWithInterface together.¶
Applications creating Endpoint objects usingWithHostNameSHOULD provide Fully QualifiedDomain Names (FQDNs). Not providing an FQDN will result in the Transport Services Implementationneeding to use DNS search domains for name resolution, which might lead to inconsistent or unpredictablebehavior.¶
The design of the APIMUST NOT permit an Endpoint object to be configured with multiple Endpoint Identifiers of the same type.For example, an Endpoint object cannot specify two IP addresses. Two separate IP addressesare represented as two Endpoint objects. If a Preconnection specifies a RemoteEndpoint with a specific IP address set, it will only establish Connections tothat IP address. If, on the other hand, a Remote Endpoint specifies a hostnamebut no addresses, the Transport Services Implementation can perform name resolution and attemptusing any address derived from the original hostname of the Remote Endpoint.Note that multiple Remote Endpoints can be added to a Preconnection, as discussedinSection 7.5.¶
The Transport Services System resolves names internally, when theInitiate,Listen, orRendezvous action is called to establish a Connection. Privacyconsiderations for the timing of this resolution are given inSection 13.¶
TheResolve action on a Preconnection can be used by the application to forceearly binding when required, for example, with some Network Address Translator(NAT) traversal protocols (seeSection 7.3).¶
To use multicast, a Preconnection is first created with the Local or Remote Endpoint Identifierspecifying the Any-Source Multicast (ASM) or Source-Specific Multicast (SSM) group and destination port number.This is then followed by a call to eitherInitiate,Listen, orRendezvous, depending on whether the resulting Connection is to beused to send Messages to the multicast group, receive Messages fromthe group, or both send andreceive Messages (as is the case for an ASM group).¶
Note that the Transport Services API has separate specifier calls for multicast groups to avoid introducing filter Properties for single-source multicast and seeks to avoid confusion that can be caused by overloading the unicast specifiers.¶
CallingInitiate on that Preconnection creates a Connection that can beused to send Messages to the multicast group. The Connection object that iscreated will supportSend but notReceive. Any Connections created thisway are send-only and do not join the multicast group. The resultingConnection will have a Local Endpoint identifying the local interface towhich the Connection is bound and a Remote Endpoint identifying themulticast group.¶
The following API calls can be used to configure a Preconnection before callingInitiate:¶
RemoteSpecifier.WithMulticastGroupIP(GroupAddress)RemoteSpecifier.WithPort(PortNumber)RemoteSpecifier.WithHopLimit(HopLimit)¶
CallingListen on a Preconnection with a multicast group address specified as the RemoteEndpoint Identifier will trigger the Transport Services Implementation to join the multicast group to receive Messages. This Listenerwill create one Connection for each Remote Endpoint sending to the group,with the Local Endpoint Identifier specified as a group address. The set of Connectionobjects created forms a Connection Group.The receiving interface can be restricted by passing it as part of the LocalSpecifier or queried through the MessageContext on the Messages received (seeSection 9.1.1 for further details).¶
SpecifyingWithHopLimit sets the Time To Live (TTL) field in the header of IPv4 packets or the Hop Count field in the header of IPv6 packets.¶
The following API calls can be used to configure a Preconnection before callingListen:¶
LocalSpecifier.WithSingleSourceMulticastGroupIP(GroupAddress, SourceAddress)LocalSpecifier.WithAnySourceMulticastGroupIP(GroupAddress)LocalSpecifier.WithPort(PortNumber)¶
CallingRendezvous on a Preconnection with an ASM groupaddress as the Remote Endpoint Identifier will trigger the Transport Services Implementation to join the multicast group and alsoindicates that the resulting Connection can be used to send Messages to the multicast group. TheRendezvous action will return both:¶
Initiate with a multicast Remote Endpoint and¶Listen had been called with a multicast RemoteEndpoint.¶CallingRendezvous on a Preconnection with an SSMgroup address as the Local Endpoint Identifier results in anEstablishmentError.¶
The following API calls can be used to configure a Preconnection before callingRendezvous:¶
RemoteSpecifier.WithMulticastGroupIP(GroupAddress)RemoteSpecifier.WithPort(PortNumber)RemoteSpecifier.WithHopLimit(HopLimit)LocalSpecifier.WithAnySourceMulticastGroupIP(GroupAddress)LocalSpecifier.WithPort(PortNumber)LocalSpecifier.WithHopLimit(HopLimit)¶
SeeSection 6.1.5 for more examples.¶
Note that this API has multiple ways to constrain and prioritize Endpoint candidates based on the network interface:¶
Specifying an interface on a Remote Endpoint qualifies the scope zone of the Remote Endpoint, e.g., for link-local addresses.¶
Specifying an interface on a Local Endpoint explicitly binds all candidates derived from this Endpoint to use the specified interface.¶
Specifying an interface using theinterface Selection Property (Section 6.2.11) or indirectly via thepvd Selection Property (Section 6.2.12) influences the selection among the available candidates.¶
While specifying an interface on an Endpoint restricts the candidates available for Connection establishment in the preestablishment phase, the Selection Properties prioritize and constrain the Connection establishment.¶
An Endpoint can have an alternative definition when using different protocols.For example, a server that supports both TLS/TCP and QUIC could be accessibleon two different port numbers, depending on which protocol is used.¶
To scope an Endpoint to apply conditionally to a specific transportprotocol (such as defining an alternate port to use when QUICis selected, as opposed to TCP), an Endpoint can beassociated with a protocol identifier. Protocol identifiers areobjects or Enumeration values provided by the TransportServices API that will vary based on which protocols areimplemented in a particular system.¶
AlternateRemoteSpecifier.WithProtocol(QUIC)¶
The following example shows a case whereexample.com has a serverrunning on port 443 with an alternate port of 8443 for QUIC. Bothendpoints can be passed when creating a Preconnection.¶
RemoteSpecifier := NewRemoteEndpoint()RemoteSpecifier.WithHostName("example.com")RemoteSpecifier.WithPort(443)QUICRemoteSpecifier := NewRemoteEndpoint()QUICRemoteSpecifier.WithHostName("example.com")QUICRemoteSpecifier.WithPort(8443)QUICRemoteSpecifier.WithProtocol(QUIC)RemoteSpecifiers := [ RemoteSpecifier, QUICRemoteSpecifier ]¶The following examples of Endpoints show common usage patterns.¶
Specify a Remote Endpoint using a hostnameexample.com and a service namehttps, which tells the system to use the default port for HTTPS (443):¶
RemoteSpecifier := NewRemoteEndpoint()RemoteSpecifier.WithHostName("example.com")RemoteSpecifier.WithService("https")¶Specify a Remote Endpoint using an IPv6 address and remote port:¶
RemoteSpecifier := NewRemoteEndpoint()RemoteSpecifier.WithIPAddress(2001:db8:4920:e29d:a420:7461:7073:a)RemoteSpecifier.WithPort(443)¶
Specify a Remote Endpoint using an IPv4 address and remote port:¶
RemoteSpecifier := NewRemoteEndpoint()RemoteSpecifier.WithIPAddress(192.0.2.21)RemoteSpecifier.WithPort(443)¶
Specify a Local Endpoint using a local interface name and no local portto let the system assign an ephemeral local port:¶
LocalSpecifier := NewLocalEndpoint()LocalSpecifier.WithInterface("en0")¶Specify a Local Endpoint using a local interface name and local port:¶
LocalSpecifier := NewLocalEndpoint()LocalSpecifier.WithInterface("en0")LocalSpecifier.WithPort(443)¶As an alternative to specifying an interface name for the Local Endpoint, an applicationcan express more fine-grained preferences using theinterfaceSelection Property; seeSection 6.2.11. However, if the application specifies SelectionProperties that are inconsistent with the Local Endpoint, this will result in an error once the application attempts to open a Connection.¶
Specify a Local Endpoint using a STUN server:¶
LocalSpecifier := NewLocalEndpoint()LocalSpecifier.WithStunServer(address, port, credentials)¶
The following examples show how multicast groups can be used.¶
Join an ASM group in receive-only mode, bound to a knownport on a named local interface:¶
RemoteSpecifier := NewRemoteEndpoint() LocalSpecifier := NewLocalEndpoint() LocalSpecifier.WithAnySourceMulticastGroupIP(233.252.0.0) LocalSpecifier.WithPort(5353) LocalSpecifier.WithInterface("en0") TransportProperties := ... SecurityParameters := ... Preconnection := NewPreconnection(LocalSpecifier, RemoteSpecifier, TransportProperties, SecurityProperties) Listener := Preconnection.Listen()¶Join an SSM group in receive-only mode, bound to a knownport on a named local interface:¶
RemoteSpecifier := NewRemoteEndpoint() LocalSpecifier := NewLocalEndpoint() LocalSpecifier.WithSingleSourceMulticastGroupIP(233.252.0.0, 198.51.100.10) LocalSpecifier.WithPort(5353) LocalSpecifier.WithInterface("en0") TransportProperties := ... SecurityParameters := ... Preconnection := NewPreconnection(LocalSpecifier, RemoteSpecifier, TransportProperties, SecurityProperties) Listener := Preconnection.Listen()¶Create an SSM group as a sender:¶
RemoteSpecifier := NewRemoteEndpoint() RemoteSpecifier.WithMulticastGroupIP(233.251.240.1) RemoteSpecifier.WithPort(5353) RemoteSpecifier.WithHopLimit(8) LocalSpecifier := NewLocalEndpoint() LocalSpecifier.WithIPAddress(192.0.2.22) LocalSpecifier.WithInterface("en0") TransportProperties := ... SecurityParameters := ... Preconnection := NewPreconnection(LocalSpecifier, RemoteSpecifier, TransportProperties, SecurityProperties) Connection := Preconnection.Initiate()¶Join an ASM group as both a sender and a receiver:¶
RemoteSpecifier := NewRemoteEndpoint() RemoteSpecifier.WithMulticastGroupIP(233.252.0.0) RemoteSpecifier.WithPort(5353) RemoteSpecifier.WithHopLimit(8) LocalSpecifier := NewLocalEndpoint() LocalSpecifier.WithAnySourceMulticastGroupIP(233.252.0.0) LocalSpecifier.WithIPAddress(192.0.2.22) LocalSpecifier.WithPort(5353) LocalSpecifier.WithInterface("en0") TransportProperties := ... SecurityParameters := ... Preconnection := NewPreconnection(LocalSpecifier, RemoteSpecifier, TransportProperties, SecurityProperties) Connection, Listener := Preconnection.Rendezvous()¶A Preconnection object holds Properties reflecting the application'srequirements and preferences for the transport. These include SelectionProperties for selecting Protocol Stacks and paths, as well as ConnectionProperties and Message Properties for configuration of the detailed operationof the selected Protocol Stacks on a per-Connection and per-Message level.¶
The protocol(s) and path(s) selected as candidates during establishment aredetermined and configured using these Properties. Since there could be pathsover which some transport protocols are unable to operate, or Remote Endpointsthat support only specific network addresses or transports, transport protocolselection is necessarily tied to path selection. This could involve choosingbetween multiple local interfaces that are connected to different accessnetworks.¶
When additional information (such as PvD information[RFC7556]) is available about the networks over which an Endpoint can operate,this can inform the selection between alternate network paths.Path information can include the Path MTU (PMTU), the set of supported Differentiated Services Code Points (DSCPs),expected usage, cost, etc. The usage of this information by the TransportServices System is generally independent of the specific mechanism or protocolused to receive the information (e.g., zero-conf, DHCP, or IPv6 Router Advertisements (RAs)).¶
Most Selection Properties are represented as Preferences, which cantake one of five values:¶
| Preference | Effect |
|---|---|
| Require | Select only protocols/paths providing the Property; otherwise, fail |
| Prefer | Prefer protocols/paths providing the Property; otherwise, proceed |
| No Preference | No preference |
| Avoid | Prefer protocols/paths not providing the Property; otherwise, proceed |
| Prohibit | Select only protocols/paths not providing the Property; otherwise, fail |
The implementationMUST ensure an outcome that is consistent with all applicationrequirements expressed usingRequire andProhibit. While preferencesexpressed usingPrefer andAvoid influence protocol and path selection as well,outcomes can vary, even given the same Selection Properties, because the availableprotocols and paths can differ across systems and contexts. However,implementations areRECOMMENDED to seek to provide a consistent outcometo an application, when provided with the same set of Selection Properties.¶
Note that application preferences can conflict with each other. Forexample, if an application indicates a preference for a specific path byspecifying an interface, but also a preference for a protocol, a situationmight occur in which the preferred protocol is not available on the preferredpath. In such cases, applications can expect Properties that determine pathselection to be prioritized over Properties that determine protocol selection.The Transport Services SystemSHOULD determine the preferred path first, regardless ofprotocol preferences. This ordering is chosen to provide consistency acrossimplementations; this is based on the fact that it is more common for the use of agiven network path to determine cost to the user (i.e., an interface typepreference might be based on a user's preference to avoid being chargedmore for a cellular data plan).¶
Selection and Connection Properties, as well as defaults for MessageProperties, can be added to a Preconnection to configure the selection processand to further configure the eventually selected Protocol Stack(s). They arecollected into a TransportProperties object to be passed into a Preconnectionobject:¶
TransportProperties := NewTransportProperties()¶
Individual Properties are then set on the TransportProperties object.Setting a Transport Property to a value overrides the previous value of this Transport Property.¶
TransportProperties.Set(property, value)¶
To aid readability, implementationsMAY provide additional convenience functions to simplify the use of Selection Properties: seeAppendix B.1 for examples.In addition, implementationsMAY provide a mechanism to create TransportProperties objects thatare preconfigured for common use cases, as outlined inAppendix B.2.¶
Transport Properties for an established Connection can be queried via the Connection object, as outlined inSection 8.¶
A Connection gets its Transport Properties by either being explicitly configuredvia a Preconnection, being configured after establishment, or inheriting themfrom an antecedent via cloning; seeSection 7.4 for more details.¶
Section 8.1 provides a list of Connection Properties, while SelectionProperties are listed in the subsections below. Selection Properties areonly considered during establishment and cannot be changed after a Connectionis established. At this point, Selection Properties can onlybe read to check the Properties used by the Connection. Upon reading, the Preference type of a Selection Property changes into Boolean, where:¶
true meansthat the selected Protocol Stack supports the feature or uses the path associatedwith the Selection Property, and¶false means that the Protocol Stack does not support the feature or use the path.¶Implementationsof Transport Services Systems could alternatively use theRequireandProhibit Preference values to representtrue andfalse, respectively.Other types of Selection Properties remain unchanged when they are made available forreading after a Connection is established.¶
An implementation of the Transport Services API needs to provide sensible defaults for SelectionProperties. The default values for each Property below represent aconfiguration that can be implemented over TCP. If these default values are usedand TCP is not supported by a Transport Services System, then an application using thedefault set of Properties might not succeed in establishing a Connection. Usingthe same default values for independent Transport Services Systems can be beneficialwhen applications are ported between different implementations/platforms, even if thisdefault could lead to a Connection failure when TCP is not available. If defaultvalues other than those suggested below are used, it isRECOMMENDED to clearlydocument any differences.¶
This Property specifies whether the application needs to use a transportprotocol that ensures thatall data is received at the Remote Endpoint in order, without loss or duplication.When reliable data transfer is enabled, thisalso entails being notified when a Connection is closed or aborted.¶
This Property specifies whether the application needs or prefers to use a transportprotocol that preserves Message boundaries.¶
This Property specifies whether an application considers it useful to specify differentreliability requirements for individual Messages in a Connection.¶
This Property specifies whether the application wishes to use a transportprotocol that can ensure that data is received by the application at the Remote Endpoint in the same order as it was sent.¶
This Property specifies whether an application would like to supply a Message tothe transport protocol before Connection establishment, which will then bereliably transferred to the Remote Endpoint before or during connectionestablishment. This Message can potentially be received multiple times (i.e.,multiple copies of the Message data could be passed to the Remote Endpoint).See alsoSection 9.1.3.4.¶
This Property specifies whether the application would prefer multiple Connectionswithin a Connection Group to be provided by streams of a single underlyingtransport connection, where possible.¶
This Property specifies the application's need for protection againstcorruption for all data transmitted on this Connection. Disabling this Property could enablethe application to influence the sender checksum coverage after Connection establishment (seeSection 9.1.3.6).¶
This Property specifies the application's need for protection againstcorruption for all data received on this Connection. Disabling this Property could enablethe application to influence the required minimum receiver checksum coverage after Connection establishment (seeSection 8.1.1).¶
This Property specifies whether or not the application would like the Connection to becongestion controlled. Note that if a Connection is not congestioncontrolled, an application using such a ConnectionSHOULD itself performcongestion control in accordance with[RFC2914] or use a circuit breaker inaccordance with[RFC8084], whichever is appropriate. Also note that reliabilityis usually combined with congestion control in protocol implementations rendering "reliable but not congestion controlled", a request that is unlikely tosucceed. If the Connection is congestion controlled, performing additional congestion controlin the application can have negative performance implications.¶
This Property specifies whether or not the application would like the Connection to sendkeep-alive packets. Note that if a Connection determines that keep-alivepackets are being sent, the application itselfSHOULD avoid generating additional keep-aliveMessages. Note that, when supported, the system will use the default periodfor generation of the keep-alive packets. (See alsoSection 8.1.4.)¶
interface¶
Set of (Preference, Enumeration)¶
Empty (not setting a Preference for any interface)¶
This Property allows the application to select any specific network interfacesor categories of interfaces it wants toRequire,Prohibit,Prefer, orAvoid. Note that marking a specific interface asRequire strictly limits pathselection to that single interface, and often leads to less flexible and resilientConnection establishment.¶
In contrast to other Selection Properties, this Property is a set oftuples of (enumerated) interface identifier and Preference. It can either beimplemented directly as such or be implemented tomake one Preference available for each interface and interface typeavailable on the system.¶
The set of valid interface types is specific to the implementation or system. Forexample, on a mobile device, there could beWi-Fi andCellular interface typesavailable; whereas, on a desktop computer,Wi-Fi andWiredEthernet interface types might be available. An implementation should provide all typesthat are supported on the local system to allowapplications to be written generically. For example, if a single implementationis used on both mobile devices and desktop devices, it ought to define theCellular interface type for both systems, since an application might wish toalways prohibit Cellular.¶
The set of interface types is expected to change over time as new accesstechnologies become available. The taxonomy of interface types on a givenTransport Services System is implementation specific.¶
Interface typesSHOULD NOT be treated as a proxy for properties of interfaces,such as metered or unmetered network access. If an application needs to prohibitmetered interfaces, this should be specified via Provisioning Domain attributes(seeSection 6.2.12) or another specific Property.¶
Note that this Property is not used to specify an interface scope zone for a particular Endpoint.Section 6.1.2 provides details about how to qualify endpoint candidates on a per-interface basis.¶
pvd¶
Set of (Preference, Enumeration)¶
Empty (not setting a Preference for any PvD)¶
Similar tointerface (seeSection 6.2.11), this Propertyallows the application to control path selection by selecting which specificPvD or categories of PvDs it wants toRequire,Prohibit,Prefer, orAvoid. Provisioning Domains defineconsistent sets of network properties that might be more specific than networkinterfaces[RFC7556].¶
As withinterface, this Property is a set of tuples of (enumerated)PvD identifier and Preference. It can either be implemented directly as such or be implemented tomake one Preference available for each interface and interface typeavailable on the system.¶
The identification of a specific PvD is specific to the implementation or system.[RFC8801] defines how to use an FQDN to identify a PvD when advertised bya network, but systems might also use other locally relevant identifierssuch as string names or Integers to identify PvDs. As with requiring specificinterfaces, requiring a specific PvD strictly limits the path selection.¶
Categories or types of PvDs are also defined to be specific to the implementation or system. These can be useful to identify a service that is provided by aPvD. For example, if an application wants to use a PvD that provides aVoice-Over-IP (VoIP) service on a Cellular network, it can use the relevant PvD type torequire a PvD that provides this service, without needing to look up aparticular instance. While this does restrict path selection, it is broader thanrequiring specific PvD instances or interface instances and should be preferredover these options.¶
useTemporaryLocalAddress¶
Preference¶
Avoid for Listeners and Rendezvous Connections;Prefer for other Connections¶
This Property allows the application to express a preference for the use oftemporary local addresses, sometimes called "privacy" addresses[RFC8981].Temporary addresses are generally used to prevent linking connections over timewhen a stable address, sometimes called a "permanent" address, is not needed.There are some caveats to note when specifying this Property. First, if anapplication requires the use of temporary addresses, the resulting Connectioncannot use IPv4 because temporary addresses do not exist in IPv4. Second,temporary local addresses might involve trading off privacy for performance.For instance, temporary addresses (e.g.,[RFC8981]) can interfere with resumption mechanismsthat some protocols rely on to reduce initial latency.¶
multipath¶
Enumeration¶
Disabled for Connections created throughInitiate andRendezvous;Passive for Listeners¶
This Property specifies whether, and how, applications want to take advantage oftransferring data across multiple paths between the same end hosts.Using multiple paths allows Connections to migrate between interfaces or aggregate bandwidthas availability and performance properties change.Possible values are as follows:¶
The Connection will not use multiple paths once established, even if the chosen transport supports using multiple paths.¶
The Connection will negotiate the use of multiple paths if the chosen transport supports it.¶
The Connection will support the use of multiple paths if the Remote Endpoint requests it.¶
The policy for using multiple paths is specified using the separatemultipathPolicy Property; seeSection 8.1.7.To enable the peer Endpoint to initiate additional paths toward a local address other than the one initially used, it is necessary to set theadvertisesAltaddr Property (seeSection 6.2.15).¶
Setting this Property toActive can have privacy implications. It enables the transport to establish connectivity using alternate paths that might result in users being linkable across the multiple paths, even if theadvertisesAltaddr Property (seeSection 6.2.15) is set tofalse.¶
Note that this Property has no corresponding Selection Property of type "Preference".Enumeration values other thanDisabled are interpreted as a preference for choosing protocols that can make use of multiple paths.TheDisabled value implies a requirement not to use multiple paths in parallel but does not prevent choosing a protocol that is capable of using multiple paths, e.g., it does not prevent choosing TCP but prevents sending theMP_CAPABLE option in the TCP handshake.¶
This Property specifies whether alternative addresses, e.g., of other interfaces, ought to be advertised to thepeer Endpoint by the Protocol Stack. Advertising these addresses enables the peer Endpoint to establish additional connectivity, e.g., for Connection migration or using multiple paths.¶
Note that this can have privacy implications because it might result in users being linkable across the multiple paths.Also, note that setting this tofalse does not prevent the local Transport Services System fromestablishing connectivity using alternate paths (seeSection 6.2.14); it only preventsproactive advertisement of addresses.¶
This Property specifies whether an application wants to use the Connection for sending and/or receiving data. Possible values are as follows:¶
The Connection must support sending and receiving data.¶
The Connection must support sending data, and the application cannot use the Connection to receive any data.¶
The Connection must support receiving data, and the application cannot use the Connection to send any data.¶
Since unidirectional communication can besupported by transports offering bidirectional communication, specifyingunidirectional communication might cause a Protocol Stack that supportsbidirectional communication to be selected.¶
This Property specifies whether an application considers it useful to beinformed when an ICMP error message arrives that does not force termination of aconnection. When set totrue, received ICMP errors are available asSoftError events; seeSection 8.3.1. Note that even if a protocol supporting this Property is selected,not all ICMP errors will necessarily be delivered, so applications cannot relyupon receiving them[RFC8085].¶
The most common client-server communication pattern involves theclient actively opening a Connection, then sending data to the server. Theserver listens (passive open), reads, and then answers. This Property specifies whether an application wants to diverge from this pattern by either:¶
Initiate, immediately followed by reading or¶Listen, immediately followed by writing.¶This Property is ignored when establishingconnections usingRendezvous.Requiring this Property limits the choice of mappings to underlying protocols,which can reduceefficiency. For example, it prevents the Transport Services System from mappingConnections to Stream Control Transmission Protocol (SCTP) streams, wherethe first transmitted data takes the role of an active open signal.¶
Most Security Parameters, e.g., TLS ciphersuites, local identity and private key, etc.,can be configured statically. Others are dynamically configured during Connection establishment.Security Parameters and callbacks are partitioned based on their place in the lifetimeof Connection establishment. Similar to Transport Properties, both parameters and callbacksare inherited during cloning (seeSection 7.4).¶
This document specifies an abstract API, which could appear to conflict with the needfor Security Parameters to be unambiguous. The Transport Services SystemSHOULD provide reasonable,secure defaults for each enumerated Security Parameter, such that users of the systemonly need to specify parameters required to establish a secure connection(e.g.,serverCertificate orclientCertificate). Specifying Security Parametersfrom enumerated values (e.g., specific ciphersuites) might constrain which transportprotocols can be selected during Connection establishment.¶
Security Parameters are specified in the preestablishment phaseand are created as follows:¶
SecurityParameters := NewSecurityParameters()¶
Specific parameters are added using a call toSet on theSecurityParameters.¶
As with the rest of the Transport Services API, the exact names of parameters and/orvalues of Enumerations (e.g., ciphersuites) used in the Security Parameters are specific to the system orimplementation and ought to be chosen to follow the principle of leastsurprise for users of the platform/language environment in question.¶
For Security Parameters that are Enumerations of known values, such as TLSciphersuites, implementations are responsible for exposing the set of valuesthey support. For Security Parameters that are not simple value types, suchas certificates and keys, implementations are responsible for exposingtypes appropriate for the platform/language environment.¶
ApplicationsSHOULD use common safe defaults for values such as TLS ciphersuiteswhenever possible. However, as discussed in[RFC8922], many transport security protocolsrequire specific Security Parameters and constraints from the client at the time ofconfiguration and actively during a handshake.¶
The set of Security Parameters defined here is not exhaustive, but illustrative.ImplementationsSHOULD expose an equivalent to the parameters listed below to allow forsufficient configuration of Security Parameters, but the details are expectedto vary based on platform and implementation constraints. ApplicationsMUST be ableto constrain the security protocols and versions that the Transport Services Systemwill use.¶
Representation of Security Parameters in implementations ought to parallelthat chosen for Transport Property names as suggested inSection 5.¶
Connections that use Transport ServicesSHOULD use security in general. However, forcompatibility with endpoints that do not support transport security protocols (suchas a TCP endpoint that does not support TLS), applications can initialize theirSecurity Parameters to indicate that security can be disabled or opportunistic.If security is disabled, the Transport Services System will not attempt to addtransport security automatically. If security is opportunistic, it will allowConnections without transport security, but it will still attempt to use unauthenticatedsecurity if available.¶
SecurityParameters := NewDisabledSecurityParameters()SecurityParameters := NewOpportunisticSecurityParameters()¶
allowedSecurityProtocols¶
Implementation-specific Enumeration of security protocol names and/or versions¶
Implementation-specific best available security protocols¶
This Property allows applications to restrict which security protocols and security protocol versions can be used in the Protocol Stack. ApplicationsMUST be able to constrain the security protocols used by this or an equivalent mechanism, in order to prevent the use of security protocols with unknown or weak security properties.¶
SecurityParameters.Set(allowedSecurityProtocols, [ tls_1_2, tls_1_3 ])¶
One or more certificate bundles identifying the Local Endpoint as a server certificate or a client certificate. Multiple bundles maybe provided to allow selection among different Protocol Stacks that mayrequire differently formatted bundles. The form and format of thecertificate bundle are implementation specific. Note that if the privatekeys associated with a bundle are not available, e.g., since they are stored in HardwareSecurity Modules (HSMs), handshake callbacks are necessary. See below for details.¶
SecurityParameters.Set(serverCertificate, myCertificateBundle[])SecurityParameters.Set(clientCertificate, myCertificateBundle[])¶
Zero or more certificate chains to use as pinned servercertificates, such that connecting will fail if the presented servercertificate does not match one of the supplied pinned certificates.The form and format of the certificate chain are implementation specific.¶
SecurityParameters.Set(pinnedServerCertificate, yourCertificateChain[])¶
Application-Layer Protocol Negotiation (ALPN) values: used to indicate whichapplication-layer protocols are negotiated by the security protocol layer.See[ALPN] for a definition of the ALPN field. Note that the TransportServices System can provide ALPN values automatically based onthe protocols being used, if not explicitly specified by the application.¶
SecurityParameters.Set(alpn, ["h2"])¶
supportedGroup, ciphersuite, signatureAlgorithm¶
Arrays of implementation-specific Enumerations¶
Automatic selection¶
These are used to restrict what cryptographic parametersare used by underlying transport security protocols. When not specified,these algorithms should use known and safe defaults for the system.¶
SecurityParameters.Set(supportedGroup, secp256r1)SecurityParameters.Set(ciphersuite, TLS_AES_128_GCM_SHA256)SecurityParameters.Set(signatureAlgorithm, ecdsa_secp256r1_sha256)¶
These values are used to tune session cache capacity and lifetime andcan be extended to include other policies.¶
SecurityParameters.Set(maxCachedSessions, 16)SecurityParameters.Set(cachedSessionLifetimeSeconds, 3600)¶
Used to install pre-shared keying material establishedout of band. Each instance of pre-shared keying material is associated with some identitythat typically identifies its use or has some protocol-specific meaning to theRemote Endpoint. Note that the use of a pre-shared key will tend to select a singlesecurity protocol and, therefore, directly select a single underlying Protocol Stack.A Transport Services API could expressNone in an environment-typical way, e.g., as a Union type or special value.¶
SecurityParameters.Set(preSharedKey, key, myIdentity)¶
Security decisions, especially pertaining to trust, are not static. Once configured,parameters can also be supplied during Connection establishment. These are besthandled as client-provided callbacks.Callbacks block the progress of the Connection establishment, which distinguishes themfrom other events in the Transport Services System. How callbacks and events are implemented is specific to each implementation.Security handshake callbacks that could be invoked during Connection establishment include:¶
Trust verification callback: Invoked when a Remote Endpoint's trust must be verified before thehandshake protocol can continue. For example, the application could verify an X.509 certificateas described in[RFC5280].¶
TrustCallback := NewCallback({ // Handle the trust and return the result})SecurityParameters.SetTrustVerificationCallback(TrustCallback)¶Identity challenge callback: Invoked when a private key operation is required, e.g., whenlocal authentication is requested by a Remote Endpoint.¶
ChallengeCallback := NewCallback({ // Handle the challenge})SecurityParameters.SetIdentityChallengeCallback(ChallengeCallback)¶Before a Connection can be used for data transfer, it needs to be established.Establishment ends the preestablishment phase; all transport Properties andcryptographic parameter specification must be complete before establishment,as these will be used to select Candidate Paths and Protocol Stacksfor the Connection. Establishment can be active, using theInitiate action;passive, using theListen action; or simultaneous for peer-to-peer connections, usingtheRendezvous action. These actions are described in the subsections below.¶
Active open is the action of establishing a Connection to a Remote Endpoint presumedto be listening for incoming Connection requests. Active open is used by clients inclient-server interactions. Active open is supported by the Transport Services API through theInitiate action:¶
Connection := Preconnection.Initiate(timeout?)¶
Thetimeout parameter specifies how long to wait before aborting active open.Before callingInitiate, the caller must have populated a Preconnectionobject with a Remote Endpoint object to identify the Endpoint, optionally a Local Endpointobject (if not specified, the system will attempt to determine asuitable Local Endpoint), as well as all Propertiesnecessary for candidate selection.¶
TheInitiate action returns a Connection object. OnceInitiate has beencalled, any changes to the PreconnectionMUST NOT have any effect on theConnection. However, the Preconnection can be reused, e.g., toInitiate another Connection.¶
OnceInitiate is called, the Candidate Protocol Stack(s) can cause one or morecandidate transport-layer connections to be created to the specified RemoteEndpoint. The caller could immediately begin sending Messages on the Connection(seeSection 9.2) after callingInitiate; note that any data marked as "safely replayable" that is sentwhile the Connection is being established could be sent multiple times or usingmultiple candidates.¶
The following events can be sent by the Connection afterInitiate is called:¶
Connection -> Ready<>¶
TheReady event occurs afterInitiate has established a transport-layerconnection on at least one usable Candidate Protocol Stack over at least oneCandidate Path. NoReceive events (seeSection 9.3) will occur beforetheReady event for Connections established usingInitiate.¶
Connection -> EstablishmentError<reason?>¶
AnEstablishmentError occurs when:¶
Connection establishmentand transmission of the first Message can be combined in a single action (Section 9.2.5).¶
Passive open is the action of waiting for Connections from Remote Endpoints,commonly used by servers in client-server interactions. Passive open issupported by the Transport Services API through theListen action and returns a Listener object:¶
Listener := Preconnection.Listen()¶
Before callingListen, the caller must have initialized the Preconnectionduring the preestablishment phase with a Local Endpoint object, as wellas all Properties necessary for Protocol Stack selection. A Remote Endpointcan optionally be specified, to constrain what Connections are accepted.¶
TheListen action returns a Listener object. OnceListen has been called,any changes to the PreconnectionMUST NOT have any effect on the Listener. ThePreconnection can be disposed of or reused, e.g., to create another Listener.¶
Listener.Stop()¶
Listening continues until the global context shuts down or until the Stopaction is performed on the Listener object.¶
Listener -> ConnectionReceived<Connection>¶
TheConnectionReceived event occurs when:¶
The resulting Connection is contained within theConnectionReceivedevent and is ready to use as soon as it is passed to the application via theevent.¶
Listener.SetNewConnectionLimit(value)¶
If the caller wants to rate-limit the number of inbound Connections that will be delivered,it can set a cap usingSetNewConnectionLimit. This mechanism allows a server toprotect itself from being drained of resources. Each time a new Connection is deliveredby theConnectionReceived event, the value is automatically decremented. Once thevalue reaches zero, no further Connections will be delivered until the caller sets thelimit to a higher value. By default, this value is Infinite. The caller is also able to resetthe value to Infinite at any point.¶
Listener -> EstablishmentError<reason?>¶
AnEstablishmentError occurs when:¶
Listener -> Stopped<>¶
AStopped event occurs after the Listener has stopped listening.¶
Simultaneous peer-to-peer Connection establishment is supported by theRendezvous action:¶
Preconnection.Rendezvous()¶
A Preconnection object used in aRendezvousMUST have both theLocal Endpoint candidates and the Remote Endpoint candidates specified,along with the Transport Properties and Security Parameters needed forProtocol Stack selection before theRendezvous action is initiated.¶
TheRendezvous action listens on the Local Endpointcandidates for an incoming Connection from the Remote Endpoint candidates,while also simultaneously trying to establish a Connection from the LocalEndpoint candidates to the Remote Endpoint candidates.¶
If there are multiple Local Endpoints or Remote Endpoints configured, theninitiating aRendezvous action will cause the Transport ServicesImplementation to systematically probe the reachabilityof those endpoint candidates following an approach such as that used inInteractive Connectivity Establishment (ICE)[RFC8445].¶
If the endpoints are suspected to be behind a NAT, and the Local Endpointsupports a method of discovering NAT bindings, such as STUN[RFC8489] or Traversal Using Relays around NAT(TURN)[RFC8656], then theResolve action on the Preconnection can beused to discover such bindings:¶
[]LocalEndpoint, []RemoteEndpoint := Preconnection.Resolve()¶
TheResolve action returns lists of Local Endpoints and Remote Endpointsthat represent the concrete addresses, local and server reflexive, on whichaRendezvous for the Preconnection will listen for incoming Connectionsand to which it will attempt to establish Connections.¶
Note that the set of Local Endpoints returned byResolve might or might notcontain information about all possible local interfaces, depending on how thePreconnection is configured. The set of available local interfaces can alsochange over time, so care needs to be taken when using stored interface names.¶
An application that usesRendezvous to establish a peer-to-peer Connectionin the presence of NATs will configure the Preconnection object with at leastone Local Endpoint that supports NAT binding discovery. It will thenResolvethe Preconnection and pass the resulting list of Local Endpoint candidates tothe peer via a signaling protocol, for example, as part of an ICE exchange[RFC8445]within SIP[RFC3261] or WebRTC[RFC7478]. The peer will then,via the same signaling channel, return the Remote Endpoint candidates.The set of Remote Endpoint candidates is then configured on the Preconnection:¶
Preconnection.AddRemote([]RemoteEndpoint)¶
Once the application hasadded both the Local Endpoint candidates and the Remote Endpoint candidatesretrieved from the peer via the signaling channel to the Preconnection,theRendezvous action is initiated and causes the Transport ServicesImplementation to begin connectivity checks.¶
If successful, theRendezvous action returns a Connection object via aRendezvousDone event:¶
Preconnection -> RendezvousDone<Connection>¶
TheRendezvousDone event occurs when a Connection is established with theRemote Endpoint. For connection-oriented transports, this occurs when thetransport-layer connection is established; for connectionless transports,it occurs when the first Message is received from the Remote Endpoint. Theresulting Connection is contained within theRendezvousDone event and isready to use as soon as it is passed to the application via the event.Changes made to a Preconnection afterRendezvous has been calledMUST NOT have any effect on existing Connections.¶
AnEstablishmentError occurs when:¶
Preconnection -> EstablishmentError<reason?>¶
Connection Groups can be created using theClone action:¶
Connection := Connection.Clone(framer?, connectionProperties?)¶
CallingClone on a Connection yields a Connection Group containing two Connections: the parentConnection on whichClone was called and a resulting cloned Connection.The new Connection is actively opened, and it will locally send aReady event or anEstablishmentError event.CallingClone on any of these Connections adds another Connection tothe Connection Group. Connections in a Connection Group share allConnection Properties exceptconnPriority (seeSection 8.1.2),and these Connection Properties are entangled: changing one of theConnection Properties on one Connection in the Connection Groupautomatically changes the Connection Property for all others. For example, changingconnTimeout (seeSection 8.1.3) on one Connection in a Connection Group will automaticallymake the same change to this Connection Property for all other Connections in the Connection Group.Like all other Properties,connPriority is copiedto the new Connection when callingClone, but, in this case, a later change to theconnPriority on one Connection does not change it on theother Connections in the same Connection Group.¶
The optionalconnectionProperties parameter allows passingTransport Properties that control the behavior of the underlying stream or connection to be created, e.g., Protocol-specific Properties to request specific stream IDs for SCTP or QUIC.¶
Message Properties set on a Connection also apply only to that Connection.¶
A new Connection created byClone can have a Message Framer assigned via the optionalframer parameter of theClone action. If this parameter is not supplied, thestack of Message Framers associated with a Connection is copied tothe cloned Connection when callingClone. Then, a cloned Connectionhas the same stack of Message Framers as the Connection from which theyare cloned, but these Framers can internally maintain per-Connection state.¶
It is also possible to check which Connections belong to the same Connection Group.CallingGroupedConnections on a specific Connection returns a set of all Connectionsin the same group.¶
[]Connection := Connection.GroupedConnections()¶
Connections will belong to the same group if the application previously calledClone.Passive Connections can also be added to the same group, e.g., when a Listenerreceives a new Connection that is just a new stream of an already-active multi-streamingprotocol instance.¶
If the underlying protocol supports multi-streaming, it is natural to use thisfunctionality to implementClone. In that case, Connections in a Connection Group aremultiplexed together, giving them similar treatment not only inside Endpoints,but also across the end-to-end Internet path.¶
Note that callingClone can result in on-the-wire signaling, e.g., to open a newtransport connection, depending on the underlying Protocol Stack. WhenClone leads tothe opening of multiple such connections,the Transport Services System will ensure consistency ofConnection Properties by uniformly applying them to all underlying connectionsin a group. Even in such a case, it is possible for a Transport Services Systemto implement prioritization within a Connection Group (see[TCP-COUPLING] and[RFC8699]).¶
Attempts to clone a Connection can result in aCloneError:¶
Connection -> CloneError<reason?>¶
ACloneError can also occur later, afterClone was successfully called. In this case,it informs the application that the Connection that sends theCloneError is no longer apart of any Connection Group. For example, this can occur when the Transport Servicessystem is unable to implement entanglement (a Connection Property was changed on a differentConnection in the Connection Group, but this change could not be successfully appliedto the Connection that sends theCloneError).¶
TheconnPriority Connection Property operates on Connections in a Connection Groupusing the same approach as that used inSection 9.1.3.2: when allocating available networkcapacity among Connections in a Connection Group, sends on Connections withnumerically lower priority values will be prioritized over sends on Connections that havenumerically higher priority values. Capacity will be shared among these Connections according totheconnScheduler Property (Section 8.1.5).SeeSection 9.2.6 for more details.¶
Transport protocols that are explicitly multipath-aware are expected to automaticallymanage the set of remote endpoints that they are communicating with and the paths tothose endpoints. APathChange event, described inSection 8.3.2, will begenerated when the path changes.¶
However, in some cases, it is necessary to explicitly indicate to a Connection thata new Remote Endpoint has become available for use or indicate that a RemoteEndpoint is no longer available. This is most common in the case of peer-to-peerconnections using Trickle ICE[RFC8838].¶
TheAddRemote action can be used to add one or more new Remote Endpointsto a Connection:¶
Connection.AddRemote([]RemoteEndpoint)¶
Endpoints that are already known to the Connection are ignored. A call toAddRemote makes the new Remote Endpoints available to the Connection,but whether the Connection makes use of those Endpoints will depend on theunderlying transport protocol.¶
Similarly, theRemoveRemote action can be used to tell a Connection tostop using one or more Remote Endpoints:¶
Connection.RemoveRemote([]RemoteEndpoint)¶
Removing all known Remote Endpoints can have the effect of aborting theconnection. The effect of removing the active Remote Endpoint(s) dependson the underlying transport: multipath-aware transports might be able toswitch to a new path if other reachable Remote Endpoints exist or theconnection might abort.¶
Similarly, theAddLocal andRemoveLocal actions can be used to addand remove Local Endpoints to or from a Connection.¶
During preestablishment and after establishment, Preconnections or Connections can be configured and queried using ConnectionProperties, and asynchronous information could be available about the state of theConnection viaSoftError events.¶
Connection Properties represent the configuration and state of the selectedProtocol Stack(s) backing a Connection. These Connection Properties can begeneric (applying regardless of transport protocol) or specific (applicable to asingle implementation of a single transport Protocol Stack). Generic ConnectionProperties are defined inSection 8.1.¶
Protocol-specific Properties are defined in a way that is specific to the transport or implementation topermit more specialized protocol features to be used.Too much reliance by an application on Protocol-specific Properties can significantly reduce the flexibilityof a Transport Services System to make appropriateselection and configuration choices. Therefore, it isRECOMMENDED thatGeneric Connection Properties be used for properties common across different protocols and thatProtocol-specific Connection Properties are only used where specific protocols or properties are necessary.¶
The application can set and query Connection Properties on a per-Connectionbasis. Connection Properties that are not read-only can be set duringpreestablishment (seeSection 6.2), as well as on Connections directly usingtheSetProperty action:¶
ErrorCode := Connection.SetProperty(property, value)¶
If an error is encountered in setting a Property (for example, if the application tries to set a TCP-specific Property on a Connection that is not using TCP), the applicationMUST be informed about this error via theErrorCode object. Such errorsMUST NOT cause the Connection to be terminated.Note that changing one of the Connection Properties on one Connection in a Connection Groupwill also change it for all other Connections of that group; seeSection 7.4.¶
At any point, the application can query Connection Properties.¶
ConnectionProperties := Connection.GetProperties()value := ConnectionProperties.Get(property)if ConnectionProperties.Has(boolean_or_preference_property) then...¶
Depending on the status of the Connection, the queried ConnectionProperties will include different information:¶
The Connection state, which can be one of the following:Establishing,Established,Closing, orClosed (seeSection 8.1.11.1).¶
Whether the Connection can be used to send data (seeSection 8.1.11.2).A Connection cannot be usedfor sending if the Connection was created with the Selection Propertydirection set toUnidirectional receive or if a Messagemarked asFinal was sent over this Connection. See alsoSection 9.1.3.5.¶
Whether the Connection can be used to receive data (seeSection 8.1.11.3).A Connection cannot beused for receiving if the Connection was created with the Selection Propertydirection set toUnidirectional send or if a Messagemarked asFinal was received (seeSection 9.3.3.3). The latteris only supported by certain transport protocols, e.g., by TCP as a half-closedconnection.¶
For Connections that areEstablished,Closing, orClosed:Connection Properties (Section 8.1) of theactual protocols that were selected and instantiated, and SelectionProperties that the application specified on the Preconnection.Selection Properties of type "Preference" will be exposed as Boolean valuesindicating whether or not the Property applies to the selected transport.Note that the instantiated Protocol Stack might not match allProtocol Selection Properties that the application specified on thePreconnection.¶
For Connections that areEstablished: Transport Services Implementationsought to provide information concerning thepath(s) used by the Protocol Stack. This can be derived from local PvD information,measurements by the Protocol Stack, or other sources.For example, a Transport Services System that is configured to receive and process PvD information[RFC7556] could also provide network configuration information for the chosen path(s).¶
Generic Connection Properties are defined independently of the chosen Protocol Stack; therefore, they are available on all Connections.¶
Many Connection Properties have a corresponding Selection Property thatenables applications to express their preference for protocols providing a supporting transport feature.¶
If this Property is an Integer, it specifies the minimum number of bytes in a receivedMessage that need to be covered by a checksum.A receiving Endpoint will not forward Messages that have less coverageto the application. The application is responsible for handlingany corruption within the non-protected part of the Message[RFC8085].A special value of 0 means that a received packet might also have a zero checksum field,and the enumerated valueFull Coverage meansthat the entire Message needs to be protected by a checksum. An implementationis supposed to expressFull Coverage in an environment-typical way, e.g., as a Union type or special value.¶
This Property is a non-negative Integer representing thepriority of this Connectionrelative to other Connections in the sameConnection Group. A numerically lower value reflects a higher priority. It has no effecton Connections not part of a ConnectionGroup. As noted inSection 7.4, this Property is not entangled when Connectionsare cloned, i.e., changing the priority on one Connection in a Connection Groupdoes not change it on the other Connections in the same Connection Group.No guarantees of a specific behavior regarding Connection Priority are given;a Transport Services System could ignore this Property. SeeSection 9.2.6 for more details.¶
If this Property is Numeric, it specifies how long to wait before deciding that an active Connection hasfailed when trying to reliably deliver data to the Remote Endpoint. Adjustments to this Propertywill only take effect if the underlying stack supports reliability. If this Property has the enumeratedvalueDisabled, it means that no timeout is scheduled. A Transport Services APIcould expressDisabled in an environment-typical way, e.g., as a Union type or special value.¶
A Transport Services API can request a protocol that supports sending keep-alive packets (Section 6.2.10).If this Property is Numeric, it specifies the maximum length of time an idle Connection (one for which no transportpackets have been sent) ought to wait beforethe Local Endpoint sends a keep-alive packet to the Remote Endpoint. Adjustments to this Propertywill only take effect if the underlying stack supports sending keep-alive packets.Guidance on setting this value for connectionless transports isprovided in[RFC8085].A value greater than the Connection timeout (Section 8.1.3) or the enumerated valueDisabled will disable the sending of keep-alive packets. A Transport Services APIcould expressDisabled in an environment-typical way, e.g., as a Union type or special value.¶
connScheduler¶
Enumeration¶
Weighted Fair Queueing (seeSection 3.6 of [RFC8260])¶
This Property specifies which scheduler is used among Connections withina Connection Group to apportion the available capacity according to Connection priorities(see Sections 7.4 and8.1.2). A set of schedulers isdescribed in[RFC8260].¶
This Property specifies the desired network treatment for traffic sent by theapplication and the trade-offs the application is prepared to make in path andprotocol selection to receive that desired treatment. When the capacity profileis set to a value other than Default, the Transport Services SystemSHOULD select pathsand configure protocols to optimize the trade-off between delay, delay variation, andefficient use of the available capacity based on the capacity profile specified. How this is realizedis implementation specific. The capacity profileMAY also be usedto set markings on the wire for Protocol Stacks supporting this action.Recommendations for use with DSCPs are provided below for each profile; note thatwhen a Connection is multiplexed, the guidelines inSection 6 of [RFC7657] apply.¶
The following values are valid for the capacity profile:¶
The application provides no information about its expected capacity profile. Transport Services Systems that map the requested capacity profile to per-connection DSCP signalingSHOULD assign the DSCP Default Forwarding Per Hop Behavior (PHB)[RFC2474].¶
The application is not interactive. It expects to send and/or receive data without any urgency. This can, for example, be used to select Protocol Stacks with scavenger transmission control and/or to assign the traffic to a lower-effort service. Transport Services Systems that map the requested capacity profile to per-connection DSCP signalingSHOULD assign the DSCP "Less than best effort" PHB[RFC8622].¶
The application is interactive and prefers loss to latency. Response timeSHOULD be optimized at the expense of delay variation and efficient use of the available capacity when sending on this Connection. TheLow Latency/Interactive value of the capacity profile can be used by the system to disable the coalescing of multiple small Messages into larger packets (Nagle algorithm (seeSection 4.2.3.4 of [RFC1122])); to prefer immediate acknowledgement from the peer Endpoint when supported by the underlying transport; and so on. Transport Services Systems that map the requested capacity profile to per-connection DSCP signaling without multiplexingSHOULD assign a DSCP Assured Forwarding (AF41, AF42, AF43, and AF44) PHB[RFC2597]. Inelastic traffic that is expected to conform to the configured network service rate could be mapped to the DSCP Expedited Forwarding PHBs[RFC3246] or PHBs as discussed in[RFC5865].¶
The application prefers loss to latency but is not interactive. Response timeSHOULD be optimized at the expense of delay variation and efficient use of the available capacity when sending on this Connection. Transport system implementations that map the requested capacity profile to per-connection DSCP signaling without multiplexingSHOULD assign a DSCP Assured Forwarding (AF21, AF22, AF23, and AF24) PHB[RFC2597].¶
The application expects to send/receive data at a constant rate after Connection establishment. Delay and delay variationSHOULD be minimized at the expense of efficient use of the available capacity. This implies that the Connection might fail if the path is unable to maintain the desired rate. A transport can interpret this capacity profile as preferring a circuit breaker[RFC8084] to a rate-adaptive congestion controller. Transport system implementations that map the requested capacity profile to per-connection DSCP signaling without multiplexingSHOULD assign a DSCP Assured Forwarding (AF31, AF32, AF33, and AF34) PHB[RFC2597].¶
The application expects to send/receive data at the maximum rate allowed by its congestion controller over a relatively long period of time. Transport Services Systems that map the requested capacity profile to per-connection DSCP signaling without multiplexingSHOULD assign a DSCP Assured Forwarding (AF11, AF12, AF13, and AF14) PHB[RFC2597] perSection 4.8 of [RFC4594].¶
The capacity profile for a selected Protocol Stack may be modified on aper-Message basis using themsgCapacityProfile Message Property; seeSection 9.1.3.8.¶
This Property specifies the local policy for transferring data across multiple paths between the same end hosts if themultipath Property is not set toDisabled (seeSection 6.2.14). Possible values are as follows:¶
The Connection ought only to attempt to migrate between different paths when the original path is lost or becomes unusable. The thresholds used to declare a path unusable are implementation specific.¶
The Connection ought only to attempt to minimize the latency for interactive traffic patterns by transmitting data across multiple paths when this is beneficial.The goal of minimizing the latency will be balanced against the cost of each of these paths. Depending on the cost of thelower-latency path, the scheduling might choose to use a higher-latency path. Traffic can be scheduled such that data may be transmittedon multiple paths in parallel to achieve a lower latency. The specific scheduling algorithm is implementation specific.¶
The Connection ought to attempt to use multiple paths in parallel to maximize available capacity and possibly overcome the capacity limitations of the individual paths. The actual strategy is implementation specific.¶
Note that this is a local choice: the Remote Endpoint can choose a different policy.¶
minSendRate / minRecvRate / maxSendRate / maxRecvRate¶
Numeric (positive) orUnlimited / Numeric (positive) orUnlimited / Numeric (positive) orUnlimited / Numeric (positive) orUnlimited¶
Unlimited /Unlimited /Unlimited /Unlimited¶
Numeric values of these Properties specify an upper-bound rate that a transfer is not expected toexceed (even if flow control and congestion control allow higher rates) and/or alower-bound application-layer rate below which the application does not deemit will be useful. These rate values are measured at the application layer, i.e., do not consider the header overheadfrom protocols used by the Transport Services System. The values are specified in bits per secondand assumed to be measured over one-second time intervals. For example, specifying a maxSendRate of X bits per secondmeans that, from the moment at which the Property value is chosen, not more than X bits will be sent in anyfollowing second. The enumerated valueUnlimited indicates that no bound is specified.A Transport Services API could expressUnlimited in an environment-typical way, e.g., as a Union type or special value.¶
If this Property is Numeric, it controls the number of Connections that can be accepted froma peer as new members of the Connection's group. Similar toSetNewConnectionLimit,this limits the number ofConnectionReceived events that will occur, but constrainedto the group of the Connection associated with this Property. For a multi-streaming transport,this limits the number of allowed streams. A Transport Services APIcould expressUnlimited in an environment-typical way, e.g., as a Union type or special value.¶
When set totrue, this Property will initiate new Connections using as littlecached information (such as session tickets or cookies) as possible fromprevious Connections that are not in the same Connection Group. Any state generated by thisConnection will only be shared with Connections in the same Connection Group. Cloned Connectionswill use saved state from within the Connection Group. This is used for separating Connection Contexts as specified inSection 4.2.3 of [RFC9621].¶
Note that this does not guarantee that information will not leak becauseimplementations might not be able to fully isolate all caches (e.g.,RTT estimates). Note that this Property could degrade Connection performance.¶
The following generic Connection Properties are read-only, i.e., they cannot be changed by an application.¶
This Property provides information about the current state of the Connection. Possible values areEstablishing,Established,Closing, orClosed. For more details on Connection state, seeSection 11.¶
This Property can be queried to learn whether the Connection can be used to send data.¶
This Property can be queried to learn whether the Connection can be used to receive data.¶
This Property, if applicable, represents the maximum Message size that can besent without incurring network-layer fragmentation at the sender.It is specified as a number of bytes and is less than or equal to themaximum Message Size onSend.It exposes a readable value to the applicationbased on the Maximum Packet Size (MPS). The value of this Property can change over time (and can be updated via Datagram Packetization Layer Path MTU Discovery (DPLPMTUD)[RFC8899]).This value allows a sending stack to avoid unwanted fragmentation at thenetwork layer or segmentation by the transport layer beforechoosing the Message size and/or after aSendError occurs indicatingan attempt to send a Message that is too large. A Transport Services APIcould expressNot applicable in an environment-typical way, e.g., as a Union type or special value (e.g., 0).¶
This Property represents the maximum Message size that an application can send.It is specified as the number of bytes. A value of 0 indicates that sending is not possible.¶
This Property represents the maximum Message size that an application can receive.It is specified as the number of bytes. A value of 0 indicates that receiving is not possible.¶
These Properties specify configurations for the TCP User Timeout Option (UTO).This is a TCP-specific Property that is only usedin the case that TCP becomes the chosen transport protocol.It is useful only if TCP is implemented in the Transport Services System.Protocol-specific options could also be defined for other transport protocols.¶
These Properties are included here because the featureSuggesttimeout to the peer is part of the minimal set of Transport Services[RFC8923], where this feature was categorized as "functional".This means that when a Transport Services System offers this feature,the Transport Services API has to expose an interface to the application. Otherwise, the implementation mightviolate assumptions by the application, which could cause the application tofail.¶
All of the below Properties are optional (e.g., it is possible to specifytcp.userTimeoutValue astruebut not specify atcp.userTimeoutValue value; in this case, the TCP default will be used).These Properties reflect the API extension specified inSection 3 of [RFC5482].¶
This time value is advertised via the TCP User Timeout Option (UTO)[RFC5482] to the Remote Endpoint, which can use it to adapt its ownconnTimeout (seeSection 8.1.3) value.¶
This Property controls whether the TCP UTO is enabled for aconnection. This applies to both sending and receiving.¶
This Property controls whether the TCPconnTimeout (seeSection 8.1.3)can be changedbased on a UTO received from the remote peer. This Boolean becomesfalse whenconnTimeout (seeSection 8.1.3) is used.¶
During the lifetime of a Connection there are events that can occur when configured.¶
Asynchronous introspection is also possible, via theSoftError event. This eventinforms the application about the receipt and contents of an ICMP error message related to the Connection. This will only happen if the underlying Protocol Stack supports access to soft errors; however, even if the underlying stack supports it, thereis no guarantee that a soft error will be signaled.¶
Connection -> SoftError<>¶
This event notifies the application when at least one of the paths underlying a Connection has changed. Changes occuron a single path when the PMTU changes as well as when multiple paths are usedand paths are added or removed, the set of Local Endpoints changes, or a handover has been performed.¶
Connection -> PathChange<>¶
Data is sent and received as Messages, which allows the applicationto communicate the boundaries of the data being transferred.¶
Each Message has an optional MessageContext, which allows adding Message Properties, to identifySend events related to a specific Message or to inspect metadata related to the Message sent. Framers can be used to extend or modify the Message data with additional information that can be processed at the receiver to detect Message boundaries.¶
Using the MessageContext object, the application can set and retrieve metadata of the Message, including Message Properties (seeSection 9.1.3) and framing metadata (seeSection 9.1.2.2).Therefore, a MessageContext object can be passed to theSend action and is returned by each event related toSend andReceive.¶
Message Properties can be set and queried using the MessageContext:¶
MessageContext.add(property, value)PropertyValue := MessageContext.get(property)¶
These Message Properties can be generic Properties or Protocol-specific Properties.¶
For MessageContexts returned bySend events (seeSection 9.2.2) andReceive events (seeSection 9.3.2), the application can query information about the Local and Remote Endpoint:¶
RemoteEndpoint := MessageContext.GetRemoteEndpoint()LocalEndpoint := MessageContext.GetLocalEndpoint()¶
Although most applications communicate over a network using well-formedMessages, the boundaries and metadata of the Messages are often notdirectly communicated by the transport protocol itself. For example,HTTP applications send and receive HTTP Messages over a byte-streamtransport, requiring that the boundaries of HTTP Messages be parsedfrom the stream of bytes.¶
Message Framers allow extending a Connection's Protocol Stack to definehow to encapsulate or encode outbound Messages and how to decapsulateor decode inbound data into Messages. Message Framers allow Messageboundaries to be preserved when using a Connection object, even whenusing byte-stream transports. This is designed based on the factthat many of the application protocols in use at the time of writing evolved over TCP, whichdoes not provide Message boundary preservation; because many of theseprotocols require Message boundaries to function, each application-layerprotocol has defined its own framing.¶
To use a Message Framer, the application adds it to its Preconnection object.Then, the Message Framer can intercept all calls toSend orReceiveon a Connection to add Message semantics, in addition to interacting withthe setup and teardown of the Connection. A Framer can start sending databefore the application sends data if the framing protocol requires a prefixor handshake (see[RFC9329] for an example of such a framing protocol).¶
Initiate() Send() Receive() Close() | | ^ | | | | | +----v----------v---------+----------v-----+ | Connection | +----+----------+---------^----------+-----+ | | | | | +-----------------+ | | | Messages | | | +-----------------+ | | | | | +----v----------v---------+----------v-----+ | Framer(s) | +----+----------+---------^----------+-----+ | | | | | +-----------------+ | | | Byte-stream | | | +-----------------+ | | | | | +----v----------v---------+----------v-----+ | Transport Protocol Stack | +------------------------------------------+
Note that while Message Framers add the most value when placed abovea protocol that otherwise does not preserve Message boundaries, they canalso be used with datagram- or message-based protocols. In these cases,they add a transformation to further encode or encapsulateand can potentially support packing multiple application-layer Messagesinto individual transport datagrams.¶
The API to implement a Message Framer can vary, depending on the implementation;guidance on implementing Message Framers can be found in[RFC9623].¶
The Message Framer object can be added to one or more Preconnectionsto run on top of transport protocols. Multiple Framers can be added to a Preconnection;in this case, the Framers operate as a framing stack, i.e., the last one added runsfirst when framing outbound Messages, and last when parsing inbound data.¶
The following example adds a basic HTTP Message Framer to a Preconnection:¶
framer := NewHTTPMessageFramer()Preconnection.AddFramer(framer)¶
Since Message Framers pass from Preconnection to Listener or Connection, addition ofFramers must happen before any operation that might result in the creation of a Connection.¶
When sending Messages, applications can add Framer-specificProperties to a MessageContext (Section 9.1.1) with theadd action.To avoid naming conflicts, the PropertynamesSHOULD be prefixed with a Namespace referencing theFramer implementation or the protocol it implements as describedinSection 4.1.¶
This mechanism can be used, for example, to set the type of a Message for a TLV format.The Namespace of values is custom for each unique Message Framer.¶
messageContext := NewMessageContext()messageContext.add(framer, key, value)Connection.Send(messageData, messageContext)¶
When an application receives a MessageContext in aReceive event,it can also look to see if a value was set by a specific Message Framer.¶
messageContext.get(framer, key) -> value¶
For example, if an HTTP Message Framer is used, the values could correspondto HTTP headers:¶
httpFramer := NewHTTPMessageFramer()...messageContext := NewMessageContext()messageContext.add(httpFramer, "accept", "text/html")¶
Applications needing to annotate the Messages they send with extra information(for example, to control how data is scheduled and processed by the transport protocols supporting the Connection) can include this information in the MessageContext passed to theSend action. For other uses of the MessageContext, seeSection 9.1.1.¶
Message Properties are per-Message, not per-Send, if partial Messagesare sent (Section 9.2.3). All data blocks associated with a single Messageshare Properties specified in the MessageContexts. For example, it would notmake sense to have the beginning of a Message expire and then allow the end of the Message to still be sent.¶
A MessageContext object contains metadata for the Messages to be sent or received.¶
messageData := "hello"messageContext := NewMessageContext()messageContext.add(parameter, value)Connection.Send(messageData, messageContext)¶
The simpler form ofSend, which does not take any MessageContext, is equivalent to passing a default MessageContext without adding any Message Properties.¶
If an application wants to override Message Properties for a specific Message,it can acquire an empty MessageContext object and add all desired MessageProperties to that object. It can then reuse the same MessageContext objectfor sending multiple Messages with the same Properties.¶
Properties can be added to a MessageContext object only before the context is usedfor sending. Once a MessageContext has been used with aSend action, further modificationsto the MessageContext object do not have any effect on thisSend action. Message Propertiesthat are not added to a MessageContext object before using the context for sending will eithertake a specific default value or be configured based on Selection or Connection Propertiesof the Connection that is associated with theSend action.This initialization behavior is defined per Message Property below.¶
The Message Properties could be inconsistent with the properties of the Protocol Stacksunderlying the Connection on which a given Message is sent. For example,a Protocol Stack must be able to provide ordering if themsgOrderedProperty of a Message is enabled. Sending a Message with Message Propertiesinconsistent with the Selection Properties of the Connection yields an error.¶
If a Message Property contradicts a Connection Property, andif this per-Message behavior can be supported, it overrides the ConnectionProperty for the specific Message. For example, ifreliability is set toRequire and a protocolwith configurable per-Message reliability is used, settingmsgReliable tofalse for a particular Message willallow this Message to be sent without any reliability guarantees. ChangingthemsgReliable Message Property is only possible forConnections that were established enabling the Selection PropertyperMsgReliability. If the contradicting Message Propertycannot be supported by the Connection (such as requiring reliabilityon a Connection that uses an unreliable protocol), theSend actionwill result in aSendError event.¶
The Message Properties in the following subsections are supported.¶
The Lifetime specifies how long a particular Message can wait in the Transport Services Systembefore it is sent to theRemote Endpoint. After this time, it is irrelevant and no longer needs to be(re-)transmitted. This is a hint to the Transport Services System -- it is not guaranteedthat a Message will not be sent when its Lifetime has expired.¶
Setting a Message's Lifetime to Infinite indicates that the application doesnot wish to apply a time constraint on the transmission of the Message, but it does not express a need forreliable delivery; reliability is adjustable per Message via theperMsgReliabilityProperty (seeSection 9.1.3.7). The type and units of Lifetime are implementation specific.¶
This Property specifies the priority of a Message, relative to other Messages sent over thesame Connection. A numerically lower value represents a higher priority.¶
A Message with priority 2 will yield to a Message with priority 1, which willyield to a Message with priority 0, and so on. Priorities can be used as asender-side scheduling construct only or be used to specify priorities on thewire for Protocol Stacks supporting prioritization.¶
Note that this Property is not a per-Message override ofconnPriority;seeSection 8.1.2. The priority Properties might interact, but they can be usedindependently and be realized by different mechanisms; seeSection 9.2.6.¶
msgOrdered¶
Boolean¶
the queried Boolean value of the Selection PropertypreserveOrder (Section 6.2.4)¶
The order in which Messages were submitted for transmission via theSend action will be preserved on delivery viaReceive events for all Messages on a Connection that have this Message Property set totrue.¶
Iffalse, the Message is delivered to the receiving application without preserving the ordering.This Property is used for protocols that support preservation of data ordering(seeSection 6.2.4) but allow out-of-order delivery for certain Messages, e.g., by multiplexing independent Messages ontodifferent streams.¶
If it is not configured by the application before sending, this Property's default valuewill be based on the Selection PropertypreserveOrder of the Connectionassociated with theSend action.¶
Iftrue,safelyReplayable specifies that a Message is safe to send to the Remote Endpointmore than once for a singleSend action. It marks the data as safe forcertain 0-RTT establishment techniques, where retransmission of the 0-RTT datacould cause the remote application to receive the Message multiple times.¶
For protocols that do not protect against duplicated Messages,e.g., UDP, all Messages need to be marked as "safely replayable" by enabling this Property.To enable protocol selection to choose such a protocol,safelyReplayable needs to be added to the TransportProperties passed to thePreconnection. If such a protocol was chosen, disablingsafelyReplayable onindividual MessagesMUST result in aSendError.¶
Iftrue, this indicates a Message is the last thatthe application will send on a Connection. This allows underlying protocolsto indicate to the Remote Endpoint that the Connection has been effectivelyclosed in the sending direction. For example, TCP-based Connections cansend a FIN once a Message marked asFinal has been completely sent,indicated by markingendOfMessage. Protocols that do not support signalingthe end of a Connection in a given direction will ignore this Property.¶
AFinal Message must always be sorted to the end of a list of Messages.Thefinal Property overridesconnPriority,msgPriority, and any other Property that would reorderMessages. If another Message is sent after a Message marked asFinal has alreadybeen sent on a Connection, theSend action for the new Message will cause aSendError event.¶
If this Property is an Integer, it specifies the minimum length of the section of a sent Message,starting from byte 0, that the application requires to be delivered withoutcorruption due to lower-layer errors. It is used to specify options for simpleintegrity protection via checksums. A value of 0 means that no checksumneeds to be calculated, and the enumerated valueFull Coverage meansthat the entire Message needs to be protected by a checksum. OnlyFull Coverage isguaranteed: any other requests are advisory, which may result inFull Coverage being applied.¶
msgReliable¶
Boolean¶
the queried Boolean value of the Selection Propertyreliability (Section 6.2.1)¶
Whentrue, this Property specifies that a Message should be sent in such a waythat the transport protocol ensures that all data is received by the Remote Endpoint.Changing themsgReliable Property on Messagesis only possible for Connections that were established enabling the Selection PropertyperMsgReliability.When this is not the case, changingmsgReliable will generate an error.¶
Disabling this Property indicates that the Transport Services System could disable retransmissionsor other reliability mechanisms for this particular Message, but such disabling is not guaranteed.¶
If it is not configured by the application before sending, this Property's default valuewill be based on the Selection Propertyreliability of the Connectionassociated with theSend action.¶
msgCapacityProfile¶
Enumeration¶
inherited from the Connection PropertyconnCapacityProfile (Section 8.1.6)¶
This enumerated Property specifies the application's preferred trade-offs forsending this Message; it is a per-Message override of theconnCapacityProfileConnection Property (seeSection 8.1.6).If it is not configured by the application before sending, this Property's default valuewill be based on the Connection PropertyconnCapacityProfile of the Connectionassociated with theSend action.¶
This Property specifies that a Message should be sent and receivedwithout network-layer fragmentation, if possible. It can be usedto avoid network-layer fragmentation when transport segmentation is preferred.¶
This only takes effect when the transport uses a network layer that supports this functionality.When it does take effect, setting this Property totrue will cause the sender to avoid network-layer source fragmentation.When using IPv4, this will result in the Don't Fragment (DF) bit being set in the IP header.¶
Attempts to send a Message with this Property that result in a size greater than thetransport's current estimate of its maximum packet size (singularTransmissionMsgMaxLen) can result in transport segmentation when permitted or in aSendError.¶
Note:noSegmentation is used when it is desired to send a Message withina single network packet.¶
When set totrue, this Property requests that the transport layer not provide segmentation of Messages larger than themaximum size permitted by the network layer and that it avoid network-layer source fragmentation of Messages.When running over IPv4, setting this Property totrue will result in a sending Endpoint setting theDon't Fragment bit in the IPv4 header of packets generated by thetransport layer.¶
Anattempt to send a Message that results in a size greater than thetransport's current estimate of its maximum packet size (singularTransmissionMsgMaxLen)will result in aSendError.This only takes effect when the transport and network layerssupport this functionality.¶
Once a Connection has been established, it can be used for sending Messages.By default,Send enqueues a complete Messageand takes optional per-Message Properties (seeSection 9.2.1). AllSend actionsare asynchronous and deliver events (seeSection 9.2.2). Sending partialMessages for streaming large data is also supported (seeSection 9.2.3).¶
Messages are sent on a Connection using theSend action:¶
Connection.Send(messageData, messageContext?, endOfMessage?)¶
wheremessageData is the data object to send andmessageContext allowsadding Message Properties, identifyingSend events related to a specificMessage or inspecting metadata related to the Message sent (seeSection 9.1.1).¶
The optionalendOfMessage parameter supports partial sending and is described inSection 9.2.3.¶
The most basic form of sending on a Connection involves enqueuing a single Datablock as a complete Message with default Message Properties.¶
messageData := "hello"Connection.Send(messageData)¶
The interpretation of a Message to be sent is dependent on the implementation and on the constraints on the Protocol Stacks implied by the Connection's transport properties. For example, a Message could be the payload ofa single datagram for a UDP connection. Another example would be an HTTP Request for an HTTPConnection.¶
Some transport protocols can deliver arbitrarily sized Messages, but otherprotocols constrain the maximum Message size. Applications can query theConnection PropertysendMsgMaxLen (Section 8.1.11.5) to determine the maximum sizeallowed for a single Message. If a Message is too large to fit in the Maximum MessageSize for the Connection, theSend will fail with aSendError event (Section 9.2.2.3). Forexample, it is invalid to send a Message over a UDP connection that is larger thanthe available datagram sending size.¶
Like all actions in the Transport Services API, theSend action is asynchronous. There areseveral events that can be delivered in response to sending a Message.Exactly one event (Sent,Expired, orSendError) will be delivered in responseto each call toSend.¶
Note that, if partialSend calls are used (Section 9.2.3), there will still be exactlyoneSend event delivered for each call toSend. For example, if a Messageexpired while two requests toSend data for that Message are outstanding,there will be twoExpired events delivered.¶
The Transport Services API should allow the application to correlate aSend event to the particular call toSend that triggered the event. The manner in which this correlation is indicatedis implementation specific.¶
Connection -> Sent<messageContext>¶
TheSent event occurs when a previousSend action has completed, i.e., whenthe data derived from the Message has been passed down or through theunderlying Protocol Stack and is no longer the responsibility ofthe Transport Services API. The exact disposition of the Message (i.e.,whether it has actually been transmitted, moved into a buffer on the networkinterface, moved into a kernel buffer, and so on) when theSent event occursis implementation specific. TheSent event contains a reference to the MessageContext of the Message to which it applies.¶
Sent events allow an application to obtain an understanding of the amountof buffering it creates. That is, if an application calls theSend action multipletimes without waiting for aSent event, it has created more buffer inside theTransport Services System than an application that always waits for theSent event beforecalling the nextSend action.¶
Connection -> Expired<messageContext>¶
TheExpired event occurs when a previousSend action expired before completion,i.e., when the Message was not sent before its Lifetime (seeSection 9.1.3.1)expired. This is separate fromSendError, as it is an expected behavior forpartially reliable transports. TheExpired event contains a reference to theMessageContext of the Message to which it applies.¶
Connection -> SendError<messageContext, reason?>¶
ASendError occurs when a Message was not sent due to an error condition:an attempt to send a Message that is too large for the system andProtocol Stack to handle, some failure of the underlying Protocol Stack, or aset of Message Properties not consistent with the Connection's transportproperties. TheSendError contains a reference to the MessageContext of theMessage to which it applies.¶
It is not always possible for an application to send all data associated witha Message in a singleSend action. The Message data might be too large forthe application to hold in memory at one time or the length of the Messagemight be unknown or unbounded.¶
Partial Message sending is supported by passing anendOfMessage Booleanparameter to theSend action. This value is alwaystrue by default, andthe simpler forms ofSend are equivalent to passingtrue forendOfMessage.¶
The following example sends a Message in two separate calls toSend:¶
messageContext := NewMessageContext()messageContext.add(parameter, value)messageData := "hel"endOfMessage := falseConnection.Send(messageData, messageContext, endOfMessage)messageData := "lo"endOfMessage := trueConnection.Send(messageData, messageContext, endOfMessage)¶
All data sent with the same MessageContext object will be treated as belongingto the same Message and will constitute an in-order series until theendOfMessage is marked.¶
To reduce the overhead of sending multiple small Messages on a Connection, theapplication could batch severalSend actions together. This provides a hint tothe system that the sending of these Messages ought to be coalesced when possibleand that sending any of the batched Messages can be delayed until the last Messagein the batch is enqueued.¶
The semantics for starting and ending a batch can be implementation specific but needto allow multipleSend actions to be enqueued.¶
Connection.StartBatch()Connection.Send(messageData)Connection.Send(messageData)Connection.EndBatch()¶
For application-layer protocols where the Connection initiator also sends thefirst Message, theInitiateWithSend action combines Connection initiation witha first Message sent:¶
Connection := Preconnection.InitiateWithSend(messageData, messageContext?, timeout?)¶
Whenever possible, amessageContext should be provided to declare the Message passed toInitiateWithSendas "safely replayable" using thesafelyReplayable Property. This allows the Transport Services System to make use of 0-RTT establishment in case this is supportedby the available Protocol Stacks. When the selected stack or stacks do not support transmitting data upon connectionestablishment,InitiateWithSend is identical toInitiate followed bySend.¶
Neither partial sends nor send batching are supported byInitiateWithSend.¶
The events that are sent afterInitiateWithSend are equivalent to thosethat would be sent by an invocation ofInitiate followed immediately by aninvocation ofSend, with the caveat that a send failure that occurs becausethe Connection could not be established will not result in aSendError separate from theEstablishmentError signaling the failure of Connectionestablishment.¶
The Transport Services API provides two Properties to allow a senderto signal the relative priority of data transmission:msgPriority (seeSection 9.1.3.2) andconnPriority (seeSection 8.1.2).These Properties are designed to allow the expressionand implementation of a wide variety of approaches to transmission priority inthe transport and application layers, including those that do not appear onthe wire (affecting only sender-side transmission scheduling) as well as thosethat do (e.g.,[RFC9218]).A Transport Services System gives no guarantees about how its expression ofrelative priorities will be realized.¶
The Transport Services API does orderconnPriority overmsgPriority. In the absence of other externalities(e.g., transport-layer flow control), a priority 1 Message on a priority 0Connection will be sent before a priority 0 Message on a priority 1Connection in the same group.¶
Once a Connection is established, it can be used for receiving data (unless thedirection Property is set tounidirectional send). As withsending, the data is received in Messages. Receiving is an asynchronousoperation in which each call toReceive enqueues a request to receive newdata from the Connection. Once data has been received, or an error is encountered,an event will be delivered to complete any pendingReceive requests (seeSection 9.3.2).If Messages arrive at the Transport Services System beforeReceive requests are issued,ensuingReceive requests will first operate on these Messages before awaiting any further Messages.¶
Receive takes two parameters to specify the length of data that an applicationis willing to receive, both of which are optional and have default values if notspecified.¶
Connection.Receive(minIncompleteLength?, maxLength?)¶
By default,Receive will try to deliver complete Messages in a single event (Section 9.3.2.1).¶
The application can set aminIncompleteLength value to indicate the smallest partialMessage data size in bytes to be delivered in response to thisReceive. By default,this value is Infinite, which means that only complete Messages should be delivered. See Sections 9.3.2.2and9.1.2 for more information on how this is accomplished.If this value is set to some smaller value, the associatedReceive event will be triggered only:¶
ApplicationsSHOULD alwayscheck the length of the data delivered to theReceive event and not assumeit will be as long asminIncompleteLength in the case of shorter complete Messagesor memory issues.¶
ThemaxLength argument indicates the maximum size of a Message in bytesthat the application is currently prepared to receive. The defaultvalue formaxLength is Infinite. If an incoming Message is larger than theminimum of this size and the maximum Message size on receive forthe Connection's Protocol Stack, it will be delivered viaReceivedPartialevents (Section 9.3.2.2).¶
Note thatmaxLength does not guarantee that the application will receive that manybytes if they are available; the Transport Services API could returnReceivedPartial events with lessdata thanmaxLength according to implementation constraints. Note also thatmaxLengthandminIncompleteLength are intended only to manage buffering and are not interpretedas a receiver preference for Message reordering.¶
Each call toReceive will be paired with a singleReceive event. This allows an applicationto provide backpressure to the Protocol Stack when it is temporarily not ready to receive Messages.For example, an application that will later be able to handle multipleReceive events at the same timecan make multiple calls toReceive without waiting for, or processing, anyReceive events. An applicationthat is temporarily unable to process received events for a connection could refrain from callingReceiveor could delay calling it. This would lead to a buildup of unread data, which, in turn, could result in backpressure to the sender via a transport protocol's flow control.¶
The Transport Services API should allow the application to correlate aReceive event to the particular call toReceive that triggered the event. The manner in which this correlation is indicatedis implementation specific.¶
Connection -> Received<messageData, messageContext>¶
AReceived event indicates the delivery of a complete Message.It contains two objects: the received bytes asmessageData and the metadata and Properties of the received Message asmessageContext.¶
ThemessageData value provides access to the bytes that were received for this Message, along with the length of the byte array.ThemessageContext value is provided to enable retrieving metadata about the Message and referring to the Message. The MessageContext object is described inSection 9.1.1.¶
SeeSection 9.1.2 regarding how to handle Message framing in situations where the ProtocolStack only provides a byte-stream transport.¶
Connection -> ReceivedPartial<messageData, messageContext, endOfMessage>¶
If a complete Message cannot be delivered in one event, one part of the Messagecan be delivered with aReceivedPartial event. To continue to receive moreof the same Message, the application must invokeReceive again.¶
Multiple invocations ofReceivedPartial deliver data for the same Message bypassing the same MessageContext until the value of theendOfMessage Property is delivered or aReceiveError occurs. All partial blocks of a single Message are delivered inorder without gaps. This event does not support delivering non-contiguous partialMessages. For example, if Message A is divided into three pieces (A1, A2, and A3), Message B is divided into three pieces (B1, B2, and B3), andpreserveOrder is notRequire,theReceivedPartial could deliver them in a sequence like this: A1, B1, B2, A2, A3, B3.This is because the MessageContext allows the application to identify the pieces as belonging to Message A and B, respectively. However, a sequence like A1, A3 will never occur.¶
If theminIncompleteLength in theReceive request was set to be Infinite (indicatinga request to receive only complete Messages), theReceivedPartial event could still bedelivered if one of the following conditions is true:¶
the underlying Protocol Stack supports Message boundary preservation andthe size of the Message is larger than the buffers available for a singleMessage;¶
the underlying Protocol Stack does not support Message boundarypreservation and the Message Framer (seeSection 9.1.2) cannot determinethe end of the Message using the buffer space it has available; or¶
the underlying Protocol Stack does not support Message boundarypreservation and no Message Framer was supplied by the application.¶
Note that, in the absence of Message boundary preservation ora Message Framer, all bytes received on the Connection will be represented as onelarge Message of indeterminate length.¶
In the following example, an application only wants to receive up to 1000 bytesat a time from a Connection. If a 1500-byte Message arrives, it would receivethe Message in two separateReceivedPartial events.¶
Connection.Receive(1, 1000)// Receive the first 1000 bytes; Message is incompleteConnection -> ReceivedPartial<messageData(1000 bytes), messageContext, false>Connection.Receive(1, 1000)// Receive the last 500 bytes; Message is now completeConnection -> ReceivedPartial<messageData(500 bytes), messageContext, true>¶
Connection -> ReceiveError<messageContext, reason?>¶
AReceiveError occurs when:¶
For example, aReceiveError canindicate that a Message (identified via themessageContext value)that was being partially received previously, but had notcompleted, encountered an error and will not be completed. This can be usefulfor an application, which might wish to use this error as a hint to removepreviously received Message parts from memory. As another example,if an incoming Message does not fulfill therecvChecksumLen Property(seeSection 8.1.1),an application can use this error as a hint to inform the peer applicationto adjust themsgChecksumLen Property (seeSection 9.1.3.6).¶
In contrast, internal protocol reception errors (e.g., loss causing retransmissionsin TCP) are not signaled by this event. Conditions that irrevocably lead tothe termination of the Connection are signaled usingConnectionError(seeSection 10).¶
Each MessageContext could contain metadata from protocols in the Protocol Stack;which metadata is available is Protocol Stack dependent. These are exposed through additional read-only Message Properties that can be queried from the MessageContext object (seeSection 9.1.1) passed by theReceive event.The metadata values in the following subsections are supported.¶
When available, Message metadata carries the value of the Explicit CongestionNotification (ECN) field. This information can be used for logging and debugging as well as building applications that need access to information aboutthe transport internals for their own operation. This Property is specific to UDPand UDP-Lite, because these protocols do not implement congestion control; hence, they expose this functionality to the application (see[RFC8293],following the guidance in[RFC8085]).¶
In some cases, it can be valuable to know whether data was read as part of earlydata transfer (before Connection establishment has finished). This is useful ifapplications need to treat early data separately,e.g., if early data has different security Properties than data sent afterConnection establishment. In the case of TLS 1.3, client early data can be replayedmaliciously (see[RFC8446]). Thus, receivers might wish to perform additionalchecks for early data to ensure that it is safely replayable. If TLS 1.3 is availableand the recipient Message was sent as part of early data, the corresponding metadata carriesa flag indicating as such. If early data is enabled, applications should check this metadatafield for Messages received during Connection establishment and respond accordingly.¶
The MessageContext can indicate whether or not this Message isthe last Message on a Connection. For any Message that is marked asFinal,the application can assume that there will be no more Messages received on theConnection once the Message has been completely delivered. This correspondsto thefinal Property that can be marked on a sent Message; seeSection 9.1.3.5.¶
Some transport protocols and peers do not support signaling of thefinal Property. Therefore,applicationsSHOULD NOT rely on receiving a Message markedFinal to knowthat the sending Endpoint is done sending on a Connection.¶
Any calls toReceive once theFinal Message has been delivered will result in errors.¶
A Connection can be terminated:¶
Close,CloseGroup,Abort, orAbortGroup action),¶Close,CloseGroup,Abort, orAbortGroup action), or¶A local call of theClose action willcause the Connection to send either aClosed event or aConnectionError event; a local call oftheCloseGroup action will cause all of the Connections in the group to send either aClosed eventor aConnectionError event. A local call of theAbort action will cause the Connection to sendaConnectionError event, indicating localAbort as areason; a local call of theAbortGroup actionwill cause all of the Connections in the group to send aConnectionError event, indicating localAbortas areason.¶
Remote action calls map to events similar to local calls (e.g., a remoteClose causes theConnection to send either aClosed event or aConnectionError event), but in contrast to local action calls,it is not guaranteed that such events will indeed be invoked. When an application needs to free resourcesassociated with a Connection, it ought not rely on the invocation of such events due totermination calls from the Remote Endpoint; instead, it should use the local termination actions.¶
Close terminates a Connection after satisfying all the requirements that werespecified regarding the delivery of Messages that the application has alreadygiven to the Transport Services System. Upon successfully satisfying all theserequirements, the Connection will send theClosed event. For example, if reliable delivery was requestedfor a Message handed over before callingClose, theClosed event will signifythat this Message has indeed been delivered. This action does not affect any other Connectionin the same Connection Group.¶
An applicationMUST NOT assume that it can receive any further data on a Connectionfor which it has calledClose, even if such data is already in flight.¶
Connection.Close()¶
TheClosed event informs the application that aClose action has successfullycompleted or that the Remote Endpoint has closed the Connection.There is no guarantee that a remoteClose will be signaled.¶
Connection -> Closed<>¶
Abort terminates a Connection without delivering any remaining Messages. This action doesnot affect any other Connection that is entangled with this one in a Connection Group.When theAbort action has finished, the Connection will send aConnectionError event,indicating localAbort as areason.¶
Connection.Abort()¶
CloseGroup gracefully terminates a Connection and any other Connections in thesame Connection Group. For example, all of the Connections in agroup might be streams of a single session for a multistreaming protocol; closing the entiregroup will close the underlying session. See alsoSection 7.4. All Connections in the groupwill send aClosed event when theCloseGroup action was successful.As withClose, any Messagesremaining to be processed on a Connection will be handled prior to closing.¶
Connection.CloseGroup()¶
AbortGroup terminates a Connection and any other Connections that arein the same Connection Group without delivering any remaining Messages.When theAbortGroup action has finished, all Connections in the group willsend aConnectionError event, indicating localAbort as areason.¶
Connection.AbortGroup()¶
AConnectionError informs the application that:¶
Abort).¶There is no guarantee that anAbort from the peer will be signaled.¶
Connection -> ConnectionError<reason?>¶
This Transport Services API is designed to be independent of an implementation'sconcurrency model. The exact details regarding how actions are handled, and howevents are dispatched, are implementation dependent.¶
Some transitions of Connection states are associated with events:¶
AReady event occurs when a Connection created withInitiate orInitiateWithSend transitions toEstablished state.¶
AConnectionReceived event occurs when a Connection created withListentransitions toEstablished state.¶
ARendezvousDone event occurs when a Connection created withRendezvoustransitions toEstablished state.¶
AClosed event occurs when a Connection transitions toClosed state without error.¶
AnEstablishmentError event occurs when a Connection created withInitiate transitionsfromEstablishing state toClosed state due to an error.¶
AConnectionError event occurs when a Connection transitions toClosed state due toan error in all other circumstances.¶
The following diagram shows the possible states of a Connection and theevents that occur upon a transition from one state to another.¶
(*) (**)Establishing -----> Established -----> Closing ------> Closed | ^ | | +---------------------------------------------------+ EstablishmentError<>(*) Ready<>, ConnectionReceived<>, RendezvousDone<>(**) Closed<>, ConnectionError<>
The Transport Services API provides the following guarantees about the ordering of operations:¶
Sent events will occur on a Connection in the order in which the Messageswere sent (i.e., delivered to the kernel or to the network interface,depending on the implementation).¶
Received events will never occur on a Connection before it isEstablished, i.e.,before aReady event on that Connection or aConnectionReceived orRendezvousDone event containing that Connection.¶
No events will occur on a Connection after it is closed, i.e., after aClosed event, anEstablishmentError orConnectionError event will not occur on that Connection. Toensure this ordering, aClosed event will not occur on a Connection while otherevents on the Connection are still locally outstanding (i.e., known to theTransport Services API and waiting to be dealt with by the application).¶
This document has no IANA actions.¶
Future works might create IANA registries for generic Transport Property names and Transport Property Namespaces (seeSection 4.1).¶
This document describes a generic API for interacting with a Transport Services System.Part of this API includes configuration details for transport security protocols, as discussedinSection 6.3. It does not recommend use (or disuse) of specificalgorithms or protocols. Any API-compatible transport security protocol ought to work in a Transport Services System.Security considerations for these protocols are discussed in the respective specifications.¶
[RFC9621] provides general security considerations and requirements for any system that implements the Transport Services Architecture. These include recommendations of relevance to the API, e.g., regarding the use of keying material.¶
The described API is used to exchange information between an application and the Transport Services System. The same authority implementing both systems is not necessarily expected. However, there is an expectation that the Transport Services Implementation would either:¶
In either case, the Transport Services API is an internal interface that is used to exchange information locally between two systems.However, as the Transport Services System is responsible for network communication, it is in the position topotentially share any information provided by the application with the network or another communication peer.Most of the information provided over the Transport Services API is useful to configure and select protocols and pathsand is not necessarily privacy sensitive. Still, some information could be privacy sensitive becauseit might reveal usage characteristics and habits of the user of an application.¶
Of course, any communication over a network reveals usage characteristics, because allpackets, as well as their timing and size, are part of the network-visible wire image[RFC8546]. However,the selection of a protocol and its configuration also impacts which information is visible, potentially inclear text, and which other entities can access it. How Transport Services Systems ought to choose protocols -- depending on the security Properties required -- is out of scope for this specification, as it is limited to transport protocols. The choice of a security protocol can be informed by the survey provided in[RFC8922].¶
In most cases, information provided for protocol and path selectiondoes not directly translate to information that can be observed by network devices on the path.However, there might be specific configurationinformation that is intended for path exposure, e.g., a Diffserv codepoint setting that is either provideddirectly by the application or indirectly configured for a traffic profile.¶
Applications should be aware that a single communication attempt can lead to more than one connection establishment procedure. For example, this is the case when:¶
Applications should take specialcare when using 0-RTT session resumption (seeSection 6.2.5), as early data sent across multiple paths duringConnection establishment could reveal information that can be used to correlate Endpoints on these paths.¶
Applications should also take care to not assume that all data received using the Transport Services API is alwayscomplete or well-formed. Specifically, Messages that are received partially (seeSection 9.3.2.2) could be a sourceof truncation attacks if applications do not distinguish between partial Messages and complete Messages.¶
The Transport Services API explicitly does not require the application to resolve names, though there isa trade-off between early and late binding of addresses to names. Early bindingallows the Transport Services Implementation to reduce Connection setup latency. This is at the costof potentially limited scope for alternate path discovery during Connectionestablishment as well as potential additional information leakage aboutapplication interest when used with a resolution method (such as DNS withoutTLS) that does not protect query confidentiality. Names used with the Transport Services APISHOULD be FQDNs; not providing an FQDN will result in the Transport Services Implementation needing to use DNS search domains for name resolution, which might lead to inconsistent or unpredictable behavior.¶
These communication activities are not different from what is used at the time of writing. However,the goal of a Transport Services System is to supportsuch mechanisms as a generic service within the transport layer. This enables applications to more dynamicallybenefit from innovations and new protocols in the transport, although it reduces transparency of theunderlying communication actions to the application itself. The Transport Services API is designed such that protocol and pathselection can belimited to a small and controlled set if required by the applicationto perform a function or to provide security.Further,introspection on the Properties of Connection objects allows an application to determine which protocol(s) and path(s) are in use.A Transport Services SystemSHOULD provide a facility logging the communication events of each Connection.¶
The way the concepts from this abstract API map to concrete APIs in agiven language on a given platform largely depends on the features and norms ofthe language and the platform. Actions could be implemented as either functions or method calls. For instance, actions could be implemented via event queues, handlerfunctions or classes, communicating sequential processes, or otherasynchronous calling conventions.¶
The basic types mentioned inSection 1.1 typically have naturalcorrespondences in practical programming languages, perhaps constrained byimplementation-specific limitations. For example:¶
Typically, an Integer can be represented in C by anint orlong; this is subjectto the underlying platform's ranges for each.¶
In C, a Tuple may be represented as astruct with one member for each ofthe value types in the ordered grouping. However, in Python, a Tuple maybe represented as atuple, which is a sequence of dynamically typedelements.¶
A Set may be represented as astd::set in C++ or as aset inPython. In C, it may be represented as an array or as a higher-level datastructure with appropriate accessors defined.¶
The objects described inSection 1.1 can also be represented indifferent ways, depending on which programming language is used. Objectslike Preconnections, Connections, and Listeners can be long-lived and benefit from using object-oriented constructs. Note that, in C, theseobjects may need to provide a way to release or free their underlyingmemory when the application is done using them. For example, since aPreconnection can be used to initiate multiple Connections, it is theresponsibility of the application to clean up the Preconnection memoryif necessary.¶
This specification treats events and errors similarly. Errors, just as anyother events, may occur asynchronously in network applications. However,implementations of this API may report errors synchronously.This is done according to the error-handling idioms of the implementationplatform, where they can be immediately detected. An example of this is to generate anexception when attempting to initiate a Connection with inconsistentTransport Properties. An error can provide an optionalreason to theapplication with further details about why the error occurred.¶
Time duration types are implementation specific.For instance, it could be a number of seconds, a number of milliseconds, or astruct timeval in C; in C++, it could be a user-definedDuration class.¶
TransportProperties will frequently need to setSelection Properties of type "Preference"; therefore, implementations can provide special actionsfor adding each preference level, i.e.,TransportProperties.Set(some_property, avoid)is equivalent toTransportProperties.Avoid(some_property):¶
TransportProperties.Require(property)TransportProperties.Prefer(property)TransportProperties.NoPreference(property)TransportProperties.Avoid(property)TransportProperties.Prohibit(property)¶
To ease the use of the Transport Services API, implementationscan provide a mechanism to create Transport Property objects (seeSection 6.2)that are preconfigured with frequently used sets of Properties; the following subsections list those that are in common use in applications at the time of writing.¶
This profile provides reliable, in-order transport service withcongestion control.TCP is an example of a protocol that provides this service.It should consist of the following Properties:¶
| Property | Value |
|---|---|
| reliability | Require |
| preserveOrder | Require |
| congestionControl | Require |
| preserveMsgBoundaries | No Preference |
This profile provides Message-preserving, reliable, in-ordertransport service with congestion control.SCTP is an example of a protocol that provides this service.It should consist of the following Properties:¶
| Property | Value |
|---|---|
| reliability | Require |
| preserveOrder | Require |
| congestionControl | Require |
| preserveMsgBoundaries | Require |
This profile provides a datagram transport service without anyreliability guarantee.An example of a protocol that provides this service is UDP.It consists of the following Properties:¶
| Property | Value |
|---|---|
| reliability | Avoid |
| preserveOrder | Avoid |
| congestionControl | No Preference |
| preserveMsgBoundaries | Require |
| safelyReplayable | true |
Applications that choose this Transport Property Profile wouldavoid the additional latency that could be introducedby retransmission or reordering in a transport protocol.¶
Applications that choose this Transport Property Profile to reduce latencyshould also consider setting an appropriate capacity profile Property(seeSection 8.1.6) and might benefit from controlling checksumcoverage (see Sections 6.2.7 and6.2.8).¶
[RFC8923] identifies a minimal set of Transport Services that end systems should offer. These services make all non-security-related transport features of TCP, Multipath TCP (MPTCP), UDP, UDP-Lite, SCTP, and Low Extra Delay Background Transport (LEDBAT) available that:¶
The following text explains how this minimal set is reflected in the present API. For brevity, it is based on the list inSection 4.1 of [RFC8923] and updated according to the discussion inSection 5 of [RFC8923]. The present API covers all elements of this section.This list is a subset of the transport features inAppendix A of [RFC8923], which refers to the primitives in "pass 2". SeeSection 4 of [RFC8303] for 1) further details on the implementation with TCP, MPTCP, UDP, UDP-Lite, SCTP, and LEDBAT and 2) how to facilitate finding the specifications for implementingthe services listed below with these protocols.¶
Initiate action (Section 7.1).¶Listen action (Section 7.2).¶timeout parameter ofInitiate (Section 7.1) orInitiateWithSend action (Section 9.2.5).¶multipath Property (Section 6.2.14).¶InitiateWithSend action (Section 9.2.5).¶connTimeout Property, using a time value (Section 8.1.3).¶ConnectionError event (Section 10).¶softErrorNotify (Section 6.2.17) andSoftError event (Section 8.3.1).¶connScheduler Property (Section 8.1.5).¶connPriority Property (Section 8.1.2).¶msgChecksumLen Property (Section 9.1.3.6) andfullChecksumSend Property (Section 6.2.7).¶recvChecksumLen Property (Section 8.1.1) andfullChecksumRecv Property (Section 6.2.8).¶noFragmentation Property (Section 9.1.3.9).¶singularTransmissionMsgMaxLen Property (Section 8.1.11.4).¶recvMsgMaxLen Property (Section 8.1.11.6).¶Low Extra Delay Background Transfer":as suggested inSection 5.5 of [RFC8923], these transport features are collectively offered via theconnCapacityProfile Property (Section 8.1.6). Per-Message control ("Request not to bundle messages") is offered via themsgCapacityProfile Property (Section 9.1.3.8).¶Close action with slightly changed semantics in line with the discussion inSection 5.2 of [RFC8923] (see alsoSection 10).¶Abort action without promising that these are signaled to the other side. If they are, aConnectionError event will be invoked at the peer (Section 10).¶Send action (Section 9.2). Reliability is controlled via thereliability (Section 6.2.1) Property and themsgReliable Message Property (Section 9.1.3.7). Transmitting data as a Message or without delimiters is controlled via Message Framers (Section 9.1.2). The choice of congestion control is provided via thecongestionControl Property (Section 6.2.9).¶msgLifetime Message Property implements a time-based way to configure Message reliability (Section 9.1.3.1).¶msgOrdered (Section 9.1.3.3).¶connCapacityProfile Property (Section 8.1.6) or themsgCapacityProfile Message Property (Section 9.1.3.8) with valueLow Latency/Interactive.¶Receive action (Section 9.3.1) andReceived event (Section 9.3.2.1).¶Receive action (Section 9.3.1) andReceived event (Section 9.3.2.1) using Message Framers (Section 9.1.2).¶Receive action (Section 9.3.1) andReceivedPartial event (Section 9.3.2.2).¶Expired event (Section 9.2.2.2) andSendError event (Section 9.2.2.3).¶Sent event (Section 9.2.2.1).¶ReceiveError event (Section 9.3.2.3).¶SoftError event (Section 8.3.1).¶This work has received funding from the European Union's Horizon 2020 research andinnovation programme under grant agreements No. 644334 (NEAT) and No. 688421 (MAMI).¶
This work has been supported by:¶
Thanks toStuart Cheshire,Josh Graessley,David Schinazi, andEric Kinnear fortheir implementation and design efforts, including Happy Eyeballs, that heavilyinfluenced this work. Thanks toLaurent Chuat andJason Lee for initial work onthe Post Sockets interface, from which this work has evolved. Thanks toMaximilian Franke for asking good questions based on implementation experienceand for contributing text, e.g., on multicast.¶