draft-ietf-taps-interface-09.txt | draft-ietf-taps-interface-10.txt | |||
---|---|---|---|---|
TAPS Working Group B. Trammell, Ed. | TAPS Working Group B. Trammell, Ed. | |||
Internet-Draft Google Switzerland GmbH | Internet-Draft Google Switzerland GmbH | |||
Intended status: Standards Track M. Welzl, Ed. | Intended status: Standards Track M. Welzl, Ed. | |||
Expires: January 28, 2021 University of Oslo | Expires: 6 May 2021 University of Oslo | |||
T. Enghardt | T. Enghardt | |||
Netflix | Netflix | |||
G. Fairhurst | G. Fairhurst | |||
University of Aberdeen | University of Aberdeen | |||
M. Kuehlewind | M. Kuehlewind | |||
Ericsson | Ericsson | |||
C. Perkins | C. Perkins | |||
University of Glasgow | University of Glasgow | |||
P. Tiesel | P. Tiesel | |||
TU Berlin | TU Berlin | |||
C. Wood | C.A. Wood | |||
Cloudflare | Cloudflare | |||
T. Pauly | T. Pauly | |||
Apple Inc. | Apple Inc. | |||
July 27, 2020 | 2 November 2020 | |||
An Abstract Application Layer Interface to Transport Services | An Abstract Application Layer Interface to Transport Services | |||
draft-ietf-taps-interface-09 | draft-ietf-taps-interface-10 | |||
Abstract | Abstract | |||
This document describes an abstract application programming | This document describes an abstract application programming | |||
interface, API, to the transport layer, following the Transport | interface, API, to the transport layer, following the Transport | |||
Services Architecture. It supports the asynchronous, atomic | Services Architecture. It supports the asynchronous, atomic | |||
transmission of messages over transport protocols and network paths | transmission of messages over transport protocols and network paths | |||
dynamically selected at runtime. It is intended to replace the | dynamically selected at runtime. It is intended to replace the | |||
traditional BSD sockets API as the common interface to the transport | traditional BSD sockets API as the common interface to the transport | |||
layer, in an environment where endpoints could select from multiple | layer, in an environment where endpoints could select from multiple | |||
skipping to change at page 2, line 7 ¶ | skipping to change at page 2, line 10 ¶ | |||
Internet-Drafts are working documents of the Internet Engineering | Internet-Drafts are working documents of the Internet Engineering | |||
Task Force (IETF). Note that other groups may also distribute | Task Force (IETF). Note that other groups may also distribute | |||
working documents as Internet-Drafts. The list of current Internet- | working documents as Internet-Drafts. The list of current Internet- | |||
Drafts is at https://datatracker.ietf.org/drafts/current/. | Drafts is at https://datatracker.ietf.org/drafts/current/. | |||
Internet-Drafts are draft documents valid for a maximum of six months | Internet-Drafts are draft documents valid for a maximum of six months | |||
and may be updated, replaced, or obsoleted by other documents at any | and may be updated, replaced, or obsoleted by other documents at any | |||
time. It is inappropriate to use Internet-Drafts as reference | time. It is inappropriate to use Internet-Drafts as reference | |||
material or to cite them other than as "work in progress." | material or to cite them other than as "work in progress." | |||
This Internet-Draft will expire on January 28, 2021. | This Internet-Draft will expire on 6 May 2021. | |||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2020 IETF Trust and the persons identified as the | Copyright (c) 2020 IETF Trust and the persons identified as the | |||
document authors. All rights reserved. | document authors. All rights reserved. | |||
This document is subject to BCP 78 and the IETF Trust's Legal | This document is subject to BCP 78 and the IETF Trust's Legal | |||
Provisions Relating to IETF Documents | Provisions Relating to IETF Documents (https://trustee.ietf.org/ | |||
(https://trustee.ietf.org/license-info) in effect on the date of | license-info) in effect on the date of publication of this document. | |||
publication of this document. Please review these documents | Please review these documents carefully, as they describe your rights | |||
carefully, as they describe your rights and restrictions with respect | and restrictions with respect to this document. Code Components | |||
to this document. Code Components extracted from this document must | extracted from this document must include Simplified BSD License text | |||
include Simplified BSD License text as described in Section 4.e of | as described in Section 4.e of the Trust Legal Provisions and are | |||
the Trust Legal Provisions and are provided without warranty as | provided without warranty as described in the Simplified BSD License. | |||
described in the Simplified BSD License. | ||||
Table of Contents | Table of Contents | |||
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 | |||
2. Terminology and Notation . . . . . . . . . . . . . . . . . . 5 | 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 5 | |||
3. Overview of Interface Design . . . . . . . . . . . . . . . . 6 | 3. Overview of Interface Design . . . . . . . . . . . . . . . . 6 | |||
4. API Summary . . . . . . . . . . . . . . . . . . . . . . . . . 7 | 4. API Summary . . . . . . . . . . . . . . . . . . . . . . . . . 7 | |||
4.1. Usage Examples . . . . . . . . . . . . . . . . . . . . . 7 | 4.1. Usage Examples . . . . . . . . . . . . . . . . . . . . . 8 | |||
4.1.1. Server Example . . . . . . . . . . . . . . . . . . . 8 | 4.1.1. Server Example . . . . . . . . . . . . . . . . . . . 8 | |||
4.1.2. Client Example . . . . . . . . . . . . . . . . . . . 9 | 4.1.2. Client Example . . . . . . . . . . . . . . . . . . . 9 | |||
4.1.3. Peer Example . . . . . . . . . . . . . . . . . . . . 10 | 4.1.3. Peer Example . . . . . . . . . . . . . . . . . . . . 10 | |||
4.2. Transport Properties . . . . . . . . . . . . . . . . . . 11 | 4.2. Transport Properties . . . . . . . . . . . . . . . . . . 11 | |||
4.2.1. Transport Property Names . . . . . . . . . . . . . . 12 | 4.2.1. Transport Property Names . . . . . . . . . . . . . . 12 | |||
4.2.2. Transport Property Types . . . . . . . . . . . . . . 13 | 4.2.2. Transport Property Types . . . . . . . . . . . . . . 13 | |||
4.3. Scope of the Interface Definition . . . . . . . . . . . . 14 | 4.3. Scope of the Interface Definition . . . . . . . . . . . . 14 | |||
5. Pre-Establishment Phase . . . . . . . . . . . . . . . . . . . 15 | 5. Pre-Establishment Phase . . . . . . . . . . . . . . . . . . . 15 | |||
5.1. Specifying Endpoints . . . . . . . . . . . . . . . . . . 15 | 5.1. Specifying Endpoints . . . . . . . . . . . . . . . . . . 16 | |||
5.2. Specifying Transport Properties . . . . . . . . . . . . . 18 | 5.1.1. Using Multicast Endpoints . . . . . . . . . . . . . . 17 | |||
5.2.1. Reliable Data Transfer (Connection) . . . . . . . . . 20 | 5.1.2. Endpoint Aliases . . . . . . . . . . . . . . . . . . 17 | |||
5.2.2. Preservation of Message Boundaries . . . . . . . . . 20 | 5.1.3. Endpoint Examples . . . . . . . . . . . . . . . . . . 18 | |||
5.2.3. Configure Per-Message Reliability . . . . . . . . . . 21 | 5.2. Specifying Transport Properties . . . . . . . . . . . . . 19 | |||
5.2.4. Preservation of Data Ordering . . . . . . . . . . . . 21 | 5.2.1. Reliable Data Transfer (Connection) . . . . . . . . . 22 | |||
5.2.2. Preservation of Message Boundaries . . . . . . . . . 22 | ||||
5.2.3. Configure Per-Message Reliability . . . . . . . . . . 22 | ||||
5.2.4. Preservation of Data Ordering . . . . . . . . . . . . 23 | ||||
5.2.5. Use 0-RTT Session Establishment with a Safely | 5.2.5. Use 0-RTT Session Establishment with a Safely | |||
Replayable Message . . . . . . . . . . . . . . . . . 21 | Replayable Message . . . . . . . . . . . . . . . . . 23 | |||
5.2.6. Multistream Connections in Group . . . . . . . . . . 22 | 5.2.6. Multistream Connections in Group . . . . . . . . . . 23 | |||
5.2.7. Full Checksum Coverage on Sending . . . . . . . . . . 22 | 5.2.7. Full Checksum Coverage on Sending . . . . . . . . . . 24 | |||
5.2.8. Full Checksum Coverage on Receiving . . . . . . . . . 22 | 5.2.8. Full Checksum Coverage on Receiving . . . . . . . . . 24 | |||
5.2.9. Congestion control . . . . . . . . . . . . . . . . . 22 | 5.2.9. Congestion control . . . . . . . . . . . . . . . . . 24 | |||
5.2.10. Interface Instance or Type . . . . . . . . . . . . . 23 | 5.2.10. Keep alive . . . . . . . . . . . . . . . . . . . . . 25 | |||
5.2.11. Provisioning Domain Instance or Type . . . . . . . . 24 | 5.2.11. Interface Instance or Type . . . . . . . . . . . . . 25 | |||
5.2.12. Use Temporary Local Address . . . . . . . . . . . . . 24 | 5.2.12. Provisioning Domain Instance or Type . . . . . . . . 26 | |||
5.2.13. Multi-Paths Transport . . . . . . . . . . . . . . . . 25 | 5.2.13. Use Temporary Local Address . . . . . . . . . . . . . 27 | |||
5.2.14. Advertisement of Alternative Addresses . . . . . . . 26 | 5.2.14. Multi-Paths Transport . . . . . . . . . . . . . . . . 27 | |||
5.2.15. Direction of communication . . . . . . . . . . . . . 26 | 5.2.15. Advertisement of Alternative Addresses . . . . . . . 28 | |||
5.2.16. Notification of excessive retransmissions . . . . . . 27 | 5.2.16. Direction of communication . . . . . . . . . . . . . 28 | |||
5.2.17. Notification of ICMP soft error message arrival . . . 27 | 5.2.17. Notification of ICMP soft error message arrival . . . 29 | |||
5.2.18. Initiating side is not the first to write . . . . . . 27 | 5.2.18. Initiating side is not the first to write . . . . . . 29 | |||
5.3. Specifying Security Parameters and Callbacks . . . . . . 28 | 5.3. Specifying Security Parameters and Callbacks . . . . . . 30 | |||
5.3.1. Pre-Connection Parameters . . . . . . . . . . . . . . 28 | 5.3.1. Pre-Connection Parameters . . . . . . . . . . . . . . 30 | |||
5.3.2. Connection Establishment Callbacks . . . . . . . . . 29 | 5.3.2. Connection Establishment Callbacks . . . . . . . . . 31 | |||
6. Establishing Connections . . . . . . . . . . . . . . . . . . 29 | 6. Establishing Connections . . . . . . . . . . . . . . . . . . 32 | |||
6.1. Active Open: Initiate . . . . . . . . . . . . . . . . . . 30 | 6.1. Active Open: Initiate . . . . . . . . . . . . . . . . . . 32 | |||
6.2. Passive Open: Listen . . . . . . . . . . . . . . . . . . 31 | 6.2. Passive Open: Listen . . . . . . . . . . . . . . . . . . 33 | |||
6.3. Peer-to-Peer Establishment: Rendezvous . . . . . . . . . 32 | 6.3. Peer-to-Peer Establishment: Rendezvous . . . . . . . . . 34 | |||
6.4. Connection Groups . . . . . . . . . . . . . . . . . . . . 33 | 6.4. Connection Groups . . . . . . . . . . . . . . . . . . . . 36 | |||
7. Managing Connections . . . . . . . . . . . . . . . . . . . . 35 | 7. Managing Connections . . . . . . . . . . . . . . . . . . . . 38 | |||
7.1. Generic Connection Properties . . . . . . . . . . . . . . 36 | 7.1. Generic Connection Properties . . . . . . . . . . . . . . 40 | |||
7.1.1. Retransmission Threshold Before Excessive | 7.1.1. Required Minimum Corruption Protection Coverage for | |||
Retransmission Notification . . . . . . . . . . . . . 37 | Receiving . . . . . . . . . . . . . . . . . . . . . . 40 | |||
7.1.2. Required Minimum Corruption Protection Coverage for | 7.1.2. Connection Priority . . . . . . . . . . . . . . . . . 40 | |||
Receiving . . . . . . . . . . . . . . . . . . . . . . 37 | 7.1.3. Timeout for Aborting Connection . . . . . . . . . . . 40 | |||
7.1.3. Priority (Connection) . . . . . . . . . . . . . . . . 37 | 7.1.4. Timeout for keep alive packets . . . . . . . . . . . 41 | |||
7.1.4. Timeout for Aborting Connection . . . . . . . . . . . 37 | 7.1.5. Connection Group Transmission Scheduler . . . . . . . 41 | |||
7.1.5. Connection Group Transmission Scheduler . . . . . . . 38 | 7.1.6. Capacity Profile . . . . . . . . . . . . . . . . . . 41 | |||
7.1.6. Capacity Profile . . . . . . . . . . . . . . . . . . 38 | 7.1.7. Policy for using Multi-Path Transports . . . . . . . 43 | |||
7.1.7. Policy for using Multi-Path Transports . . . . . . . 40 | 7.1.8. Bounds on Send or Receive Rate . . . . . . . . . . . 44 | |||
7.1.8. Bounds on Send or Receive Rate . . . . . . . . . . . 40 | 7.1.9. Group Connection Limit . . . . . . . . . . . . . . . 44 | |||
7.1.9. Read-only Connection Properties . . . . . . . . . . . 41 | 7.1.10. Read-only Connection Properties . . . . . . . . . . . 44 | |||
7.2. TCP-specific Properties: User Timeout Option (UTO) . . . 42 | 7.2. TCP-specific Properties: User Timeout Option (UTO) . . . 45 | |||
7.2.1. Advertised User Timeout . . . . . . . . . . . . . . . 42 | 7.2.1. Advertised User Timeout . . . . . . . . . . . . . . . 46 | |||
7.2.2. User Timeout Enabled . . . . . . . . . . . . . . . . 42 | 7.2.2. User Timeout Enabled . . . . . . . . . . . . . . . . 46 | |||
7.2.3. Timeout Changeable . . . . . . . . . . . . . . . . . 43 | 7.2.3. Timeout Changeable . . . . . . . . . . . . . . . . . 46 | |||
7.3. Connection Lifecycle Events . . . . . . . . . . . . . . . 43 | 7.3. Connection Lifecycle Events . . . . . . . . . . . . . . . 47 | |||
7.3.1. Soft Errors . . . . . . . . . . . . . . . . . . . . . 43 | 7.3.1. Soft Errors . . . . . . . . . . . . . . . . . . . . . 47 | |||
7.3.2. Excessive retransmissions . . . . . . . . . . . . . . 43 | 7.3.2. Path change . . . . . . . . . . . . . . . . . . . . . 47 | |||
8. Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . 43 | 8. Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . 47 | |||
8.1. Messages and Framers . . . . . . . . . . . . . . . . . . 43 | 8.1. Messages and Framers . . . . . . . . . . . . . . . . . . 47 | |||
8.1.1. Message Contexts . . . . . . . . . . . . . . . . . . 44 | 8.1.1. Message Contexts . . . . . . . . . . . . . . . . . . 48 | |||
8.1.2. Message Framers . . . . . . . . . . . . . . . . . . . 44 | 8.1.2. Message Framers . . . . . . . . . . . . . . . . . . . 48 | |||
8.1.3. Message Properties . . . . . . . . . . . . . . . . . 46 | 8.1.3. Message Properties . . . . . . . . . . . . . . . . . 50 | |||
8.2. Sending Data . . . . . . . . . . . . . . . . . . . . . . 51 | 8.2. Sending Data . . . . . . . . . . . . . . . . . . . . . . 56 | |||
8.2.1. Basic Sending . . . . . . . . . . . . . . . . . . . . 52 | 8.2.1. Basic Sending . . . . . . . . . . . . . . . . . . . . 56 | |||
8.2.2. Sending Replies . . . . . . . . . . . . . . . . . . . 52 | 8.2.2. Send Events . . . . . . . . . . . . . . . . . . . . . 57 | |||
8.2.3. Send Events . . . . . . . . . . . . . . . . . . . . . 52 | 8.2.3. Partial Sends . . . . . . . . . . . . . . . . . . . . 58 | |||
8.2.4. Partial Sends . . . . . . . . . . . . . . . . . . . . 54 | 8.2.4. Batching Sends . . . . . . . . . . . . . . . . . . . 58 | |||
8.2.5. Batching Sends . . . . . . . . . . . . . . . . . . . 54 | 8.2.5. Send on Active Open: InitiateWithSend . . . . . . . . 59 | |||
8.2.6. Send on Active Open: InitiateWithSend . . . . . . . . 55 | 8.2.6. Priority in TAPS . . . . . . . . . . . . . . . . . . 59 | |||
8.3. Receiving Data . . . . . . . . . . . . . . . . . . . . . 60 | ||||
8.3. Receiving Data . . . . . . . . . . . . . . . . . . . . . 55 | 8.3.1. Enqueuing Receives . . . . . . . . . . . . . . . . . 60 | |||
8.3.1. Enqueuing Receives . . . . . . . . . . . . . . . . . 56 | 8.3.2. Receive Events . . . . . . . . . . . . . . . . . . . 61 | |||
8.3.2. Receive Events . . . . . . . . . . . . . . . . . . . 56 | 8.3.3. Receive Message Properties . . . . . . . . . . . . . 63 | |||
8.3.3. Receive Message Properties . . . . . . . . . . . . . 58 | 9. Connection Termination . . . . . . . . . . . . . . . . . . . 64 | |||
9. Connection Termination . . . . . . . . . . . . . . . . . . . 59 | 10. Connection State and Ordering of Operations and Events . . . 65 | |||
10. Connection State and Ordering of Operations and Events . . . 60 | 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 66 | |||
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 61 | 12. Privacy and Security Considerations . . . . . . . . . . . . . 66 | |||
12. Security Considerations . . . . . . . . . . . . . . . . . . . 61 | 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 68 | |||
13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 63 | 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 68 | |||
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 63 | 14.1. Normative References . . . . . . . . . . . . . . . . . . 68 | |||
14.1. Normative References . . . . . . . . . . . . . . . . . . 63 | 14.2. Informative References . . . . . . . . . . . . . . . . . 69 | |||
14.2. Informative References . . . . . . . . . . . . . . . . . 64 | Appendix A. Convenience Functions . . . . . . . . . . . . . . . 72 | |||
Appendix A. Convenience Functions . . . . . . . . . . . . . . . 67 | A.1. Adding Preference Properties . . . . . . . . . . . . . . 72 | |||
A.1. Adding Preference Properties . . . . . . . . . . . . . . 67 | A.2. Transport Property Profiles . . . . . . . . . . . . . . . 73 | |||
A.2. Transport Property Profiles . . . . . . . . . . . . . . . 67 | A.2.1. reliable-inorder-stream . . . . . . . . . . . . . . . 73 | |||
A.2.1. reliable-inorder-stream . . . . . . . . . . . . . . . 67 | A.2.2. reliable-message . . . . . . . . . . . . . . . . . . 73 | |||
A.2.2. reliable-message . . . . . . . . . . . . . . . . . . 67 | A.2.3. unreliable-datagram . . . . . . . . . . . . . . . . . 74 | |||
A.2.3. unreliable-datagram . . . . . . . . . . . . . . . . . 68 | Appendix B. Relationship to the Minimal Set of Transport Services | |||
Appendix B. Relationship to the Minimal Set of Transport | for End Systems . . . . . . . . . . . . . . . . . . . . . 74 | |||
Services for End Systems . . . . . . . . . . . . . . 68 | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 77 | |||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 72 | ||||
1. Introduction | 1. Introduction | |||
This document specifies a modern abstract application programming | This document specifies a modern abstract application programming | |||
interface (API) atop the high-level architecture for transport | interface (API) atop the high-level architecture for transport | |||
services defined in [I-D.ietf-taps-arch]. It supports the | services defined in [I-D.ietf-taps-arch]. It supports the | |||
asynchronous, atomic transmission of messages over transport | asynchronous, atomic transmission of messages over transport | |||
protocols and network paths dynamically selected at runtime. It is | protocols and network paths dynamically selected at runtime. It is | |||
intended to replace the traditional BSD sockets API as the common | intended to replace the traditional BSD sockets API as the common | |||
interface to the transport layer, in environments where endpoints | interface to the transport layer, in environments where an endpoint | |||
select from multiple interfaces and potential transport protocols. | selects from multiple interfaces and potential transport protocols. | |||
As applications adopt this interface, they will benefit from a wide | As applications adopt this interface, they will benefit from a wide | |||
set of transport features that can evolve over time, and ensure that | set of transport features that can evolve over time, and ensure that | |||
the system providing the interface can optimize its behavior based on | the system providing the interface can optimize its behavior based on | |||
the application requirements and network conditions, without | the application requirements and network conditions, without | |||
requiring changes to the applications. This flexibility enables | requiring changes to the applications. This flexibility enables | |||
faster deployment of new features and protocols. It can also support | faster deployment of new features and protocols. It can also support | |||
applications by offering racing and fallback mechanisms, which | applications by offering racing and fallback mechanisms, which | |||
otherwise need to be separately implemented in each application. | otherwise need to be separately implemented in each application. | |||
It derives specific path and protocol selection properties and | It derives specific path and protocol selection properties and | |||
supported transport features from the analysis provided in [RFC8095], | supported transport features from the analysis provided in [RFC8095], | |||
[I-D.ietf-taps-minset], and [I-D.ietf-taps-transport-security]. The | [RFC8923], and [RFC8922]. The design encourages implementations | |||
design encourages implementations underneath the interface to | underneath the interface to dynamically choose a transport protocol | |||
dynamically choose a transport protocol depending on an application's | depending on an application's choices rather than statically binding | |||
choices rather than statically binding applications to a protocol at | applications to a protocol at compile time. The transport system | |||
compile time. The transport system implementations should provide | implementations should provide applications with a way to override | |||
applications with a way to override transport selection and | transport selection and instantiate a specific stack, e.g., to | |||
instantiate a specific stack, e.g., to support servers wishing to | support servers wishing to listen to a specific protocol. This | |||
listen to a specific protocol. This specific transport stack choice | specific transport stack choice is discouraged for general use, | |||
is discouraged for general use, because it can reduce the | because it can reduce the portability. | |||
portability. | ||||
2. Terminology and Notation | 2. Terminology and Notation | |||
This API is described in terms of Objects with which an application | This API is described in terms of Objects with which an application | |||
can interact; Actions the application can perform on these Objects; | can interact; Actions the application can perform on these Objects; | |||
Events, which an Object can send to an application asynchronously; | Events, which an Object can send to an application asynchronously; | |||
and Parameters associated with these Actions and Events. | and Parameters associated with these Actions and Events. | |||
The following notations, which can be combined, are used in this | The following notations, which can be combined, are used in this | |||
document: | document: | |||
o An Action creates an Object: | * An Action creates an Object: | |||
Object := Action() | Object := Action() | |||
o An Action creates an array of Objects: | * An Action creates an array of Objects: | |||
[]Object := Action() | []Object := Action() | |||
o An Action is performed on an Object: | * An Action is performed on an Object: | |||
Object.Action() | Object.Action() | |||
o An Object sends an Event: | * An Object sends an Event: | |||
Object -> Event<> | Object -> Event<> | |||
o An Action takes a set of Parameters; an Event contains a set of | * An Action takes a set of Parameters; an Event contains a set of | |||
Parameters. Action and Event parameters whose names are suffixed | Parameters. Action and Event parameters whose names are suffixed | |||
with a question mark are optional. | with a question mark are optional. | |||
Action(param0, param1?, ...) / Event<param0, param1, ...> | Action(param0, param1?, ...) / Event<param0, param1, ...> | |||
Actions associated with no Object are Actions on the abstract | Actions associated with no Object are Actions on the abstract | |||
interface itself; they are equivalent to Actions on a per-application | interface itself; they are equivalent to Actions on a per-application | |||
global context. | global context. | |||
The way these abstract concepts map into concrete implementations of | The way these abstract concepts map into concrete implementations of | |||
this API in a given language on a given platform largely depends on | this API in a given language on a given platform largely depends on | |||
the features of the language and the platform. Actions could be | the features of the language and the platform. Actions could be | |||
implemented as functions or method calls, for instance, and Events | implemented as functions or method calls, for instance, and Events | |||
could be implemented via event queues, handler functions or classes, | could be implemented via event queues, handler functions or classes, | |||
communicating sequential processes, or other asynchronous calling | communicating sequential processes, or other asynchronous calling | |||
conventions. | conventions. | |||
This specification treats Events and errors similarly. Errors, just | This specification treats Events and Errors similarly. Errors, just | |||
as any other Events, may occur asynchronously in network | as any other Events, may occur asynchronously in network | |||
applications. However, it is recommended that implementations of | applications. However, it is recommended that implementations of | |||
this interface also return errors immediately, according to the error | this interface also return Errors immediately, according to the error | |||
handling idioms of the implementation platform, for errors that can | handling idioms of the implementation platform, for errors that can | |||
be immediately detected, such as inconsistency in Transport | be immediately detected, such as inconsistency in Transport | |||
Properties. Errors can provide an optional reason to give the | Properties. An error can provide an optional reason to the | |||
application further details as to why the error occurred. | application with further details about why the error occurred. | |||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | |||
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and | "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and | |||
"OPTIONAL" in this document are to be interpreted as described in BCP | "OPTIONAL" in this document are to be interpreted as described in BCP | |||
14 [RFC2119] [RFC8174] when, and only when, they appear in all | 14 [RFC2119] [RFC8174] when, and only when, they appear in all | |||
capitals, as shown here. | capitals, as shown here. | |||
3. Overview of Interface Design | 3. Overview of Interface Design | |||
The design of the interface specified in this document is based on a | The design of the interface specified in this document is based on a | |||
set of principles, themselves an elaboration on the architectural | set of principles, themselves an elaboration on the architectural | |||
design principles defined in [I-D.ietf-taps-arch]. The interface | design principles defined in [I-D.ietf-taps-arch]. The interface | |||
defined in this document provides: | defined in this document provides: | |||
o A single interface to a variety of transport protocols to be used | * Access to a variety of transport protocols, independent of the the | |||
in a variety of application design patterns, independent of the | Protocol Stacks that will be used at runtime, such that all common | |||
properties of the application and the Protocol Stacks that will be | features of these protocol stacks are made available to the | |||
used at runtime, such that all common specialized features of | application in a transport-independent way to the degree possible, | |||
these protocol stacks are made available to the application as | enabling applications written to a single API to make use of | |||
necessary in a transport-independent way, to enable applications | transport protocols in terms of the features they provide; | |||
written to a single API to make use of transport protocols in | ||||
terms of the features they provide; | ||||
o Message-orientation, as opposed to stream-orientation, using | * Message-orientation, as opposed to stream-orientation, using | |||
application-assisted framing and deframing where the underlying | application-assisted framing and deframing where the underlying | |||
transport does not provide these; | transport does not provide these; | |||
o Asynchronous Connection establishment, transmission, and | * Asynchronous Connection establishment, transmission, and | |||
reception, allowing concurrent operations during establishment and | reception, allowing concurrent operations during establishment and | |||
supporting event-driven application interactions with the | supporting event-driven application interactions with the | |||
transport layer, in line with developments in modern platforms and | transport layer, in line with developments in modern platforms and | |||
programming languages; | programming languages; | |||
o Explicit support for security properties as first-order transport | * Explicit support for transport-specific features to be applied | |||
should that particular transport be part of a chosen Protocol | ||||
Stack. | ||||
* Explicit support for security properties as first-order transport | ||||
features, and for configuration of cryptographic identities and | features, and for configuration of cryptographic identities and | |||
transport security parameters persistent across multiple | transport security parameters persistent across multiple | |||
Connections; and | Connections; and | |||
o Explicit support for multistreaming and multipath transport | * Explicit support for multistreaming and multipath transport | |||
protocols, and the grouping of related Connections into Connection | protocols, and the grouping of related Connections into Connection | |||
Groups through cloning of Connections, to allow applications to | Groups through cloning of Connections, to allow applications to | |||
take full advantage of new transport protocols supporting these | take full advantage of new transport protocols supporting these | |||
features. | features. | |||
4. API Summary | 4. API Summary | |||
The Transport Services API is the basic common abstract application | The Transport Services API is the basic common abstract application | |||
programming interface to the Transport Services Architecture defined | programming interface to the Transport Services Architecture defined | |||
in the TAPS Architecture [I-D.ietf-taps-arch]. | in the TAPS Architecture [I-D.ietf-taps-arch]. | |||
An application primarily interacts with this API through two Objects: | An application primarily interacts with this API through two Objects: | |||
Preconnections and Connections. A Preconnection represents a set of | Preconnections and Connections. A Preconnection represents a set of | |||
properties and constraints on the selection and configuration of | properties and constraints on the selection and configuration of | |||
paths and protocols to establish a Connection with a remote Endpoint. | paths and protocols to establish a Connection with a Remote Endpoint. | |||
A Connection represents a transport Protocol Stack on which data can | A Connection represents a transport Protocol Stack on which data can | |||
be sent to and/or received from a remote Endpoint (i.e., depending on | be sent to and/or received from a Remote Endpoint (i.e., depending on | |||
the kind of transport, connections can be bi-directional or | the kind of transport, connections can be bi-directional or | |||
unidirectional). Connections can be created from Preconnections in | unidirectional). Connections can be created from Preconnections in | |||
three ways: by initiating the Preconnection (i.e., actively opening, | three ways: by initiating the Preconnection (i.e., actively opening, | |||
as in a client), through listening on the Preconnection (i.e., | as in a client), through listening on the Preconnection (i.e., | |||
passively opening, as in a server), or rendezvousing on the | passively opening, as in a server), or rendezvousing on the | |||
Preconnection (i.e. peer to peer establishment). | Preconnection (i.e. peer to peer establishment). | |||
Once a Connection is established, data can be sent and received on it | Once a Connection is established, data can be sent and received on it | |||
in the form of Messages. The interface supports the preservation of | in the form of Messages. The interface supports the preservation of | |||
message boundaries both via explicit Protocol Stack support, and via | message boundaries both via explicit Protocol Stack support, and via | |||
application support through a Message Framer which finds message | application support through a Message Framer which finds message | |||
boundaries in a stream. Messages are received asynchronously through | boundaries in a stream. Messages are received asynchronously through | |||
event handlers registered by the application. Errors and other | event handlers registered by the application. Errors and other | |||
notifications also happen asynchronously on the Connection. It is | notifications also happen asynchronously on the Connection. It is | |||
not necessary for an application to handle all events; some events | not necessary for an application to handle all Events; some Events | |||
may have implementation-specific default handlers. The application | may have implementation-specific default handlers. The application | |||
should not assume that ignoring events (e.g. errors) is always safe. | should not assume that ignoring Events (e.g., Errors) is always safe. | |||
Section 5, Section 6, Section 8.2, Section 8.3, and Section 9 | Section 5, Section 6, Section 8.2, Section 8.3, and Section 9 | |||
describe the details of application interaction with Objects through | describe the details of application interaction with Objects through | |||
Actions and Events in each phase of a Connection, following the | Actions and Events in each phase of a Connection, following the | |||
phases (Pre-Establishment, Establishment, Data Transfer, and | phases (Pre-Establishment, Establishment, Data Transfer, and | |||
Termination) described in Section 4.1 of [I-D.ietf-taps-arch]. | Termination) described in Section 4.1 of [I-D.ietf-taps-arch]. | |||
4.1. Usage Examples | 4.1. Usage Examples | |||
The following usage examples illustrate how an application might use | The following usage examples illustrate how an application might use | |||
a Transport Services Interface to: | a Transport Services Interface to: | |||
o Act as a server, by listening for incoming connections, receiving | * Act as a server, by listening for incoming connections, receiving | |||
requests, and sending responses, see Section 4.1.1. | requests, and sending responses, see Section 4.1.1. | |||
o Act as a client, by connecting to a remote endpoint using | * Act as a client, by connecting to a Remote Endpoint using | |||
Initiate, sending requests, and receiving responses, see | Initiate, sending requests, and receiving responses, see | |||
Section 4.1.2. | Section 4.1.2. | |||
o Act as a peer, by connecting to a remote endpoint using Rendezvous | * Act as a peer, by connecting to a Remote Endpoint using Rendezvous | |||
while simultaneously waiting for incoming Connections, sending | while simultaneously waiting for incoming Connections, sending | |||
Messages, and receiving Messages, see Section 4.1.3. | Messages, and receiving Messages, see Section 4.1.3. | |||
The examples in this section presume that a transport protocol is | The examples in this section presume that a transport protocol is | |||
available between the endpoints that provides Reliable Data Transfer, | available between the Local and Remote Endpoints that provides | |||
Preservation of data ordering, and Preservation of Message | Reliable Data Transfer, Preservation of data ordering, and | |||
Boundaries. In this case, the application can choose to receive only | Preservation of Message Boundaries. In this case, the application | |||
complete messages. | can choose to receive only complete messages. | |||
If none of the available transport protocols provides Preservation of | If none of the available transport protocols provides Preservation of | |||
Message Boundaries, but there is a transport protocol that provides a | Message Boundaries, but there is a transport protocol that provides a | |||
reliable ordered byte stream, an application may receive this byte | reliable ordered byte stream, an application could receive this byte | |||
stream as partial Messages and transform it into application-layer | stream as partial Messages and transform it into application-layer | |||
Messages. Alternatively, an application may provide a Message | Messages. Alternatively, an application might provide a Message | |||
Framer, which can transform a byte stream into a sequence of Messages | Framer, which can transform a sequence of Messages into a byte stream | |||
(Section 8.1.2). | and vice versa (Section 8.1.2). | |||
4.1.1. Server Example | 4.1.1. Server Example | |||
This is an example of how an application might listen for incoming | This is an example of how an application might listen for incoming | |||
Connections using the Transport Services Interface, receive a | Connections using the Transport Services Interface, and receive a | |||
request, and send a response. | request, and send a response. | |||
LocalSpecifier := NewLocalEndpoint() | LocalSpecifier := NewLocalEndpoint() | |||
LocalSpecifier.WithInterface("any") | LocalSpecifier.WithInterface("any") | |||
LocalSpecifier.WithService("https") | LocalSpecifier.WithService("https") | |||
TransportProperties := NewTransportProperties() | TransportProperties := NewTransportProperties() | |||
TransportProperties.Require(preserve-msg-boundaries) | TransportProperties.Require(preserve-msg-boundaries) | |||
// Reliable Data Transfer and Preserve Order are Required by default | // Reliable Data Transfer and Preserve Order are Required by default | |||
SecurityParameters := NewSecurityParameters() | SecurityParameters := NewSecurityParameters() | |||
SecurityParameters.AddIdentity(identity) | SecurityParameters.Set('identity', identity) | |||
SecurityParameters.AddPrivateKey(privateKey, publicKey) | SecurityParameters.Set('keypair', privateKey, publicKey) | |||
// Specifying a remote endpoint is optional when using Listen() | // Specifying a remote endpoint is optional when using Listen() | |||
Preconnection := NewPreconnection(LocalSpecifier, | Preconnection := NewPreconnection(LocalSpecifier, | |||
TransportProperties, | TransportProperties, | |||
SecurityParameters) | SecurityParameters) | |||
Listener := Preconnection.Listen() | Listener := Preconnection.Listen() | |||
Listener -> ConnectionReceived<Connection> | Listener -> ConnectionReceived<Connection> | |||
skipping to change at page 9, line 42 ¶ | skipping to change at page 9, line 42 ¶ | |||
Connection.Send(messageDataResponse) | Connection.Send(messageDataResponse) | |||
Connection.Close() | Connection.Close() | |||
// Stop listening for incoming Connections | // Stop listening for incoming Connections | |||
// (this example supports only one Connection) | // (this example supports only one Connection) | |||
Listener.Stop() | Listener.Stop() | |||
//---- Receive event handler end ---- | //---- Receive event handler end ---- | |||
4.1.2. Client Example | 4.1.2. Client Example | |||
This is an example of how an application might connect to a remote | This is an example of how an application might open two Connections | |||
application using the Transport Services Interface, send a request, | to a remote application using the Transport Services Interface, and | |||
and receive a response. | send a request as well as receive a response on each of them. | |||
RemoteSpecifier := NewRemoteEndpoint() | RemoteSpecifier := NewRemoteEndpoint() | |||
RemoteSpecifier.WithHostname("example.com") | RemoteSpecifier.WithHostname("example.com") | |||
RemoteSpecifier.WithService("https") | RemoteSpecifier.WithService("https") | |||
TransportProperties := NewTransportProperties() | TransportProperties := NewTransportProperties() | |||
TransportProperties.Require(preserve-msg-boundaries) | TransportProperties.Require(preserve-msg-boundaries) | |||
// Reliable Data Transfer and Preserve Order are Required by default | // Reliable Data Transfer and Preserve Order are Required by default | |||
SecurityParameters := NewSecurityParameters() | SecurityParameters := NewSecurityParameters() | |||
skipping to change at page 10, line 25 ¶ | skipping to change at page 10, line 25 ¶ | |||
// Verify identity of the remote endpoint, return the result | // Verify identity of the remote endpoint, return the result | |||
}) | }) | |||
SecurityParameters.SetTrustVerificationCallback(TrustCallback) | SecurityParameters.SetTrustVerificationCallback(TrustCallback) | |||
// Specifying a local endpoint is optional when using Initiate() | // Specifying a local endpoint is optional when using Initiate() | |||
Preconnection := NewPreconnection(RemoteSpecifier, | Preconnection := NewPreconnection(RemoteSpecifier, | |||
TransportProperties, | TransportProperties, | |||
SecurityParameters) | SecurityParameters) | |||
Connection := Preconnection.Initiate() | Connection := Preconnection.Initiate() | |||
Connection2 := Connection.Clone() | ||||
Connection -> Ready<> | Connection -> Ready<> | |||
Connection2 -> Ready<> | ||||
//---- Ready event handler begin ---- | //---- Ready event handler for any Connection C begin ---- | |||
Connection.Send(messageDataRequest) | C.Send(messageDataRequest) | |||
// Only receive complete messages | // Only receive complete messages | |||
Connection.Receive() | C.Receive() | |||
//---- Ready event handler end ---- | //---- Ready event handler for any Connection C end ---- | |||
Connection -> Received<messageDataResponse, messageContext> | Connection -> Received<messageDataResponse, messageContext> | |||
Connection2 -> Received<messageDataResponse, messageContext> | ||||
// Close the Connection in a Receive event handler | // Close the Connection in a Receive event handler | |||
Connection.Close() | Connection.Close() | |||
Connection2.Close() | ||||
4.1.3. Peer Example | 4.1.3. Peer Example | |||
This is an example of how an application might establish a connection | This is an example of how an application might establish a connection | |||
with a peer using Rendezvous(), send a Message, and receive a | with a peer using Rendezvous(), send a Message, and receive a | |||
Message. | Message. | |||
LocalSpecifier := NewLocalEndpoint() | LocalSpecifier := NewLocalEndpoint() | |||
LocalSpecifier.WithPort(9876) | LocalSpecifier.WithPort(9876) | |||
RemoteSpecifier := NewRemoteEndpoint() | RemoteSpecifier := NewRemoteEndpoint() | |||
RemoteSpecifier.WithHostname("example.com") | RemoteSpecifier.WithHostname("example.com") | |||
RemoteSpecifier.WithPort(9877) | RemoteSpecifier.WithPort(9877) | |||
TransportProperties := NewTransportProperties() | TransportProperties := NewTransportProperties() | |||
TransportProperties.Require(preserve-msg-boundaries) | TransportProperties.Require(preserve-msg-boundaries) | |||
// Reliable Data Transfer and Preserve Order are Required by default | // Reliable Data Transfer and Preserve Order are Required by default | |||
SecurityParameters := NewSecurityParameters() | SecurityParameters := NewSecurityParameters() | |||
SecurityParameters.AddIdentity(identity) | SecurityParameters.Set('identity', identity) | |||
SecurityParameters.AddPrivateKey(privateKey, publicKey) | SecurityParameters.Set('keypair', privateKey, publicKey) | |||
TrustCallback := New Callback({ | TrustCallback := New Callback({ | |||
// Verify identity of the remote endpoint, return the result | // Verify identity of the remote endpoint, return the result | |||
}) | }) | |||
SecurityParameters.SetTrustVerificationCallback(trustCallback) | SecurityParameters.SetTrustVerificationCallback(trustCallback) | |||
// Both local and remote endpoint must be specified | // Both local and remote endpoint must be specified | |||
Preconnection := NewPreconnection(LocalSpecifier, | Preconnection := NewPreconnection(LocalSpecifier, | |||
RemoteSpecifier, | RemoteSpecifier, | |||
TransportProperties, | TransportProperties, | |||
skipping to change at page 12, line 6 ¶ | skipping to change at page 12, line 6 ¶ | |||
Connection.Close() | Connection.Close() | |||
4.2. Transport Properties | 4.2. Transport Properties | |||
Each application using the Transport Services Interface declares its | Each application using the Transport Services Interface declares its | |||
preferences for how the transport service should operate using | preferences for how the transport service should operate using | |||
properties at each stage of the lifetime of a connection using | properties at each stage of the lifetime of a connection using | |||
Transport Properties, as defined in [I-D.ietf-taps-arch]. | Transport Properties, as defined in [I-D.ietf-taps-arch]. | |||
Transport Properties are divided into Selection, Connection, and | Transport Properties are divided into Selection, Connection, and | |||
Message Properties. Selection Properties (see Section 5.2) can only | Message Properties. Selection Properties (see The behavior of the | |||
be set during pre-establishment. They are only used to specify which | selected protocol stack(s) when sending Messages is controlled by | |||
paths and protocol stacks can be used and are preferred by the | Message Properties (see Section 5.2) can only be set during pre- | |||
application. Connection Properties (see Section 7.1) can also be set | establishment. They are only used to specify which paths and | |||
during pre-establishment but may be changed later. They are used to | protocol stacks can be used and are preferred by the application. | |||
Although Connection Properties (see Section 7.1) can be set during | ||||
pre-establishment, they may be changed later. They are used to | ||||
inform decisions made during establishment and to fine-tune the | inform decisions made during establishment and to fine-tune the | |||
established connection. | established connection.Section 8.1.3). | |||
The behavior of the selected protocol stack(s) when sending Messages | ||||
is controlled by Message Properties (see Section 8.1.3). | ||||
All Transport Properties, regardless of the phase in which they are | All Transport Properties, regardless of the phase in which they are | |||
used, are organized within a single namespace. This enables setting | used, are organized within a single namespace. This enables setting | |||
them as defaults in earlier stages and querying them in later stages: | them as defaults at earlier stages and querying them in later stages: | |||
o Connection Properties can be set on Preconnections | * Connection Properties can be set on Preconnections and Connections | |||
o Message Properties can be set on Preconnections, Connections and | * Message Properties can be set on Preconnections, Connections and | |||
Messages | Messages | |||
o The effect of Selection Properties can be queried on Connections | * The effect of Selection Properties can be queried on Connections | |||
and Messages | and Messages | |||
Note that configuring Connection Properties and Message Properties on | Note that configuring Connection Properties and Message Properties on | |||
Preconnections is preferred over setting them later. Early | Preconnections is preferred over setting them later. Early | |||
specification of Connection Properties allows their use as additional | specification of Connection Properties allows their use as additional | |||
input to the selection process. Protocol Specific Properties, which | input to the selection process. Protocol Specific Properties, which | |||
enable configuration of specialized features of a specific protocol, | enable configuration of specialized features of a specific protocol, | |||
see Section 3.2 of [I-D.ietf-taps-arch], are not used as an input to | see Section 3.2 of [I-D.ietf-taps-arch], are not used as an input to | |||
the selection process but only support configuration if the | the selection process but only support configuration if the | |||
respective protocol has been selected. | respective protocol has been selected. | |||
4.2.1. Transport Property Names | 4.2.1. Transport Property Names | |||
Transport Properties are referred to by property names. For the | Transport Properties are referred to by property names. For the | |||
purposes of this document, these names are alphanumeric strings in | purposes of this document, these names are alphanumeric strings in | |||
which words may be separated by hyphens. These names serve two | which words may be separated by hyphens. These names serve two | |||
purposes: | purposes: | |||
o Allowing different components of a TAPS implementation to pass | * Allowing different components of a TAPS implementation to pass | |||
Transport Properties, e.g., between a language frontend and a | Transport Properties, e.g., between a language frontend and a | |||
policy manager, or as a representation of properties retrieved | policy manager, or as a representation of properties retrieved | |||
from a file or other storage. | from a file or other storage. | |||
o Making code of different TAPS implementations look similar. While | * Making the code of different TAPS implementations look similar. | |||
individual programming languages may preclude strict adherence to | While individual programming languages may preclude strict | |||
the aforementioned naming convention (for instance, by prohibiting | adherence to the aforementioned naming convention (for instance, | |||
the use of hyphens in symbols), users interacting with multiple | by prohibiting the use of hyphens in symbols), users interacting | |||
implementations will still benefit from the consistency resulting | with multiple implementations will still benefit from the | |||
from the use of visually similar symbols. | consistency resulting from the use of visually similar symbols. | |||
Transport Property Names are hierarchically organized in the form | Transport Property Names are hierarchically organized in the form | |||
[<Namespace>.]<PropertyName>. | [<Namespace>.]<PropertyName>. | |||
o The Namespace component MUST be empty for well-known, generic | * The Namespace component MUST be empty for well-known, generic | |||
properties, i.e., for properties that are not specific to a | properties, i.e., for properties that are not specific to a | |||
protocol and are defined in an RFC. | protocol and are defined in an RFC. | |||
o Protocol Specific Properties MUST use the protocol acronym as | * Protocol Specific Properties MUST use the protocol acronym as the | |||
Namespace, e.g., "tcp" for TCP specific Transport Properties. For | Namespace, e.g., "tcp" for TCP specific Transport Properties. For | |||
IETF protocols, property names under these namespaces SHOULD be | IETF protocols, property names under these namespaces SHOULD be | |||
defined in an RFC. | defined in an RFC. | |||
o Vendor or implementation specific properties MUST use a string | * Vendor or implementation specific properties MUST use a string | |||
identifying the vendor or implementation as Namespace. | identifying the vendor or implementation as the Namespace. | |||
Namespaces for each of the keywords provided in the IANA protocol | Namespaces for each of the keywords provided in the IANA protocol | |||
numbers registry (see https://www.iana.org/assignments/protocol- | numbers registry (see https://www.iana.org/assignments/protocol- | |||
numbers/protocol-numbers.xhtml), reformatted where necessary to | numbers/protocol-numbers.xhtml), reformatted where necessary to | |||
conform to an implementation's naming conventions, are reserved for | conform to an implementation's naming conventions, are reserved for | |||
Protocol Specific Properties and MUST not be used for vendor or | Protocol Specific Properties and MUST NOT be used for vendor or | |||
implementation-specific properties. | implementation-specific properties. | |||
4.2.2. Transport Property Types | 4.2.2. Transport Property Types | |||
Transport Properties can have one of a set of data types: | Transport Properties can have one of a set of data types: | |||
o Boolean: can take the values "true" and "false"; representation is | * Boolean: can take the values "true" and "false"; representation is | |||
implementation-dependent. | implementation-dependent. | |||
o Integer: can take positive or negative numeric integer values; | * Integer: can take positive or negative numeric integer values; | |||
range and representation is implementation-dependent. | range and representation is implementation-dependent. | |||
o Numeric: can take positive or negative numeric values; range and | * Numeric: can take positive or negative numeric values; range and | |||
representation is implementation-dependent. | representation is implementation-dependent. | |||
o Enumeration: can take one value of a finite set of values, | * Enumeration: can take one value of a finite set of values, | |||
dependent on the property itself. The representation is | dependent on the property itself. The representation is | |||
implementation dependent; however, implementations MUST provide a | implementation dependent. | |||
method for the application to determine the entire set of possible | ||||
values for each property. | ||||
o Preference: can take one of five values (Prohibit, Avoid, Ignore, | * Preference: can take one of five values (Prohibit, Avoid, Ignore, | |||
Prefer, Require) for the level of preference of a given property | Prefer, Require) for the level of preference of a given property | |||
during protocol selection; see Section 5.2. When querying, a | during protocol selection; see Section 5.2. When querying, a | |||
Preference is of type Boolean, with "true" indicating that the | Preference is of type Boolean, with "true" indicating that the | |||
Selection Property has been applied. | Selection Property has been applied. | |||
* Tuple: An ordered grouping of multiple value types. In this this | ||||
document, it is written as a list in brackets, e.g., | ||||
"(Enumeration, Preference)" The composition of types and their | ||||
order depends on the property and is fixed for the property. The | ||||
actual representation is implementation-dependent. | ||||
* Collection: An unordered grouping of one or more values of the | ||||
same type. The actual representation, e.g. as a set or an array, | ||||
is implementation-dependent. | ||||
For types Integer and Numeric, special values can be defined per | For types Integer and Numeric, special values can be defined per | |||
property; it is up to implementations how these special values are | property; it is up to implementations how these special values are | |||
represented (e.g., by using -1 for an otherwise non-negative value). | represented (e.g., by using -1 for an otherwise non-negative value). | |||
4.3. Scope of the Interface Definition | 4.3. Scope of the Interface Definition | |||
This document defines a language- and platform-independent interface | This document defines a language- and platform-independent interface | |||
to a Transport Services system. Given the wide variety of languages | to a Transport Services system. Given the wide variety of languages | |||
and language conventions used to write applications that use the | and language conventions used to write applications that use the | |||
transport layer to connect to other applications over the Internet, | transport layer to connect to other applications over the Internet, | |||
this independence makes this interface necessarily abstract. | this independence makes this interface necessarily abstract. | |||
There is no interoperability benefit in tightly defining how the | There is no interoperability benefit in tightly defining how the | |||
interface is presented to application programmers across diverse | interface is presented to application programmers across diverse | |||
platforms. However, maintaining the "shape" of the abstract | platforms. However, maintaining the "shape" of the abstract | |||
interface across these platforms reduces the effort for programmers | interface across different platforms reduces the effort for | |||
who learn the transport services interface to then apply their | programmers who learn the transport services interface to then apply | |||
knowledge across multiple platforms. | their knowledge to another platform. | |||
We therefore make the following recommendations: | We therefore make the following recommendations: | |||
o Actions, Events, and Errors in implementations of this interface | * Actions, Events, and Errors in implementations of this interface | |||
SHOULD use the names given for them in the document, subject to | SHOULD use the names given for them in the document, subject to | |||
capitalization, punctuation, and other typographic conventions in | capitalization, punctuation, and other typographic conventions in | |||
the language of the implementation, unless the implementation | the language of the implementation, unless the implementation | |||
itself uses different names for substantially equivalent objects | itself uses different names for substantially equivalent objects | |||
for networking by convention. | for networking by convention. | |||
o Implementations of this interface SHOULD implement each Selection | * Implementations of this interface SHOULD implement each Selection | |||
Property, Connection Property, and Message Context Property | Property, Connection Property, and Message Context Property | |||
specified in this document. Each interface SHOULD be implemented | specified in this document. Each interface SHOULD be implemented | |||
even when this will always result in no operation, e.g. there is | even when in a specific implementation/platform it will always | |||
no action when the API specifies a Property that is not available | result in no operation, e.g. there is no action when the API | |||
in a transport protocol implemented on a specific platform. For | specifies a Property that is not available in a transport protocol | |||
example, if TCP is the only underlying transport protocol, the | implemented on a specific platform. For example, if TCP is the | |||
Message Property "msgOrdered" can be implemented even if disabling | only underlying transport protocol, the Message Property | |||
ordering will not have any effect TCP because the API does not | "msgOrdered" can be implemented (trivially, as a no-op) as | |||
guarantee out-of-order delivery. Similarly, the "msg-lifetime" | disabling the requirement for ordering will not have any effect on | |||
Message Property can be implemented but ignored, as the | delivery order for Connections over TCP. Similarly, the "msg- | |||
lifetime" Message Property can be implemented but ignored, as the | ||||
description of this Property states that "it is not guaranteed | description of this Property states that "it is not guaranteed | |||
that a Message will not be sent when its Lifetime has expired". | that a Message will not be sent when its Lifetime has expired". | |||
o Implementations may use other representations for Transport | * Implementations may use other representations for Transport | |||
Property Names, e.g., by providing constants, but should provide a | Property Names, e.g., by providing constants, but should provide a | |||
straight-forward mapping between their representation and the | straight-forward mapping between their representation and the | |||
property names specified here. | property names specified here. | |||
5. Pre-Establishment Phase | 5. Pre-Establishment Phase | |||
The Pre-Establishment phase allows applications to specify properties | The Pre-Establishment phase allows applications to specify properties | |||
for the Connections they are about to make, or to query the API about | for the Connections that they are about to make, or to query the API | |||
potential Connections they could make. | about potential Connections they could make. | |||
A Preconnection Object represents a potential Connection. It has | A Preconnection Object represents a potential Connection. It has | |||
state that describes properties of a Connection that might exist in | state that describes the properties of a Connection that might exist | |||
the future. This state comprises Local Endpoint and Remote Endpoint | in the future. This state comprises Local Endpoint and Remote | |||
Objects that denote the endpoints of the potential Connection (see | Endpoint Objects that denote the endpoints of the potential | |||
Section 5.1), the Selection Properties (see Section 5.2), any | Connection (see Section 5.1), the Selection Properties (see | |||
preconfigured Connection Properties (Section 7.1), and the security | Section 5.2), any preconfigured Connection Properties (Section 7.1), | |||
parameters (see Section 5.3): | and the security parameters (see Section 5.3): | |||
Preconnection := NewPreconnection(LocalEndpoint?, | Preconnection := NewPreconnection(LocalEndpoint?, | |||
RemoteEndpoint?, | RemoteEndpoint?, | |||
TransportProperties, | TransportProperties, | |||
SecurityParams) | SecurityParameters) | |||
The Local Endpoint MUST be specified if the Preconnection is used to | The Local Endpoint MUST be specified if the Preconnection is used to | |||
Listen() for incoming Connections, but is OPTIONAL if it is used to | Listen() for incoming Connections, but is OPTIONAL if it is used to | |||
Initiate() connections. If no Local Endpoint is specified, the | Initiate() connections. If no Local Endpoint is specified, the | |||
Transport System will assign an ephemeral local port to the | Transport System will assign an ephemeral local port to the | |||
Connection. The Remote Endpoint MUST be specified if the | Connection on the appropriate interface(s). The Remote Endpoint MUST | |||
Preconnection is used to Initiate() Connections, but is OPTIONAL if | be specified if the Preconnection is used to Initiate() Connections, | |||
it is used to Listen() for incoming Connections. The Local Endpoint | but is OPTIONAL if it is used to Listen() for incoming Connections. | |||
and the Remote Endpoint MUST both be specified if a peer-to-peer | The Local Endpoint and the Remote Endpoint MUST both be specified if | |||
Rendezvous is to occur based on the Preconnection. | a peer-to-peer Rendezvous is to occur based on the Preconnection. | |||
Transport Properties MUST always be specified while security | Transport Properties MUST always be specified while security | |||
parameters are OPTIONAL. | parameters are OPTIONAL. | |||
If Message Framers are used (see Section 8.1.2), they MUST be added | If Message Framers are used (see Section 8.1.2), they MUST be added | |||
to the Preconnection during pre-establishment. | to the Preconnection during pre-establishment. | |||
5.1. Specifying Endpoints | 5.1. Specifying Endpoints | |||
The transport services API uses the Local Endpoint and Remote | The transport services API uses the Local Endpoint and Remote | |||
Endpoint Objects to refer to the endpoints of a transport connection. | Endpoint Objects to refer to the endpoints of a transport connection. | |||
Actions on these Objects can be used to represent various different | Endpoints can be created as either Remote or Local: | |||
types of endpoint identifiers, such as IP addresses, DNS names, and | ||||
interface names, as well as port numbers and service names. | RemoteSpecifier := NewRemoteEndpoint() | |||
LocalSpecifier := NewLocalEndpoint() | ||||
A single Endpoint Object represents the identity of a network host. | ||||
That endpoint can be more or less specific depending on which | ||||
identifiers are set. For example, an Endpoint that only specifies a | ||||
hostname may in fact end up corresponding to 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 integer) or a Service (string) that maps to a port | ||||
RemoteSpecifier.WithPort(443) | ||||
RemoteSpecifier.WithService("https") | ||||
* IP address (IPv4 or IPv6 address) | ||||
RemoteSpecifier.WithIPv4Address(192.0.2.21) | ||||
RemoteSpecifier.WithIPv6Address(2001:db8:4920:e29d:a420:7461:7073:0a) | ||||
* Interface (string name) | ||||
LocalSpecifier.WithInterface("en0") | ||||
An Endpoint cannot have multiple identifiers of a same type set. | ||||
That is, an endpoint cannot have two IP addresses specified. Two | ||||
separate IP addresses are represented as two Endpoint Objects. If a | ||||
Preconnection specifies a Remote Endpoint with a specific IP address | ||||
set, it will only establish Connections to that IP address. If, on | ||||
the other hand, the Remote Endpoint specifies a hostname but no | ||||
addresses, the Connection can perform name resolution and attempt | ||||
using any address derived from the original hostname of the Remote | ||||
Endpoint. | ||||
The Transport Services API resolves names internally, when the | ||||
Initiate(), Listen(), or Rendezvous() method is called to establish a | ||||
Connection. Privacy considerations for the timing of this resolution | ||||
are given in Section 12. | ||||
The Resolve() action on a Preconnection can be used by the | ||||
application to force early binding when required, for example with | ||||
some Network Address Translator (NAT) traversal protocols (see | ||||
Section 6.3). | ||||
5.1.1. Using Multicast Endpoints | ||||
Specifying a multicast group address on a Local Endpoint will | ||||
indicate to the transport system that the resulting connection will | ||||
be used to receive multicast messages. The Remote Endpoint can be | ||||
used to filter incoming multicast from specific senders. Such a | ||||
Preconnection will only support calling Listen(), not Initiate(). | ||||
The accepted Connections are receive-only. | ||||
Similarly, specifying a multicast group address on the Remote | ||||
Endpoint will indicate that the resulting connection will be used to | ||||
send multicast messages. | ||||
5.1.2. Endpoint Aliases | ||||
An Endpoint can have an alternative definition when using different | ||||
protocols. For example, a server that supports both TLS/TCP and QUIC | ||||
may be accessible on two different port numbers depending on which | ||||
protocol is used. | ||||
To support this, Endpoint Objects can specify "aliases". An Endpoint | ||||
can have multiple aliases set. | ||||
RemoteSpecifier.AddAlias(AlternateRemoteSpecifier) | ||||
In order to scope an alias to a specific transport protocol, an | ||||
Endpoint can specify a protocol identifier. These identifiers MUST | ||||
only be set for aliases. | ||||
RemoteSpecifier.WithProtocol(QUIC) | ||||
The following example shows a case where "example.com" has a server | ||||
running on port 443, with an alternate port of 8443 for QUIC. | ||||
RemoteSpecifier := NewRemoteEndpoint() | ||||
RemoteSpecifier.WithHostname("example.com") | ||||
RemoteSpecifier.WithPort(443) | ||||
QUICRemoteSpecifier := NewRemoteEndpoint() | ||||
QUICRemoteSpecifier.WithHostname("example.com") | ||||
QUICRemoteSpecifier.WithPort(8443) | ||||
QUICRemoteSpecifier.WithProtocol(QUIC) | ||||
RemoteSpecifier.AddAlias(QUICRemoteSpecifier) | ||||
5.1.3. Endpoint Examples | ||||
The following examples of Endpoints show common usage patterns. | ||||
Specify a Remote Endpoint using a hostname and service name: | Specify a Remote Endpoint using a hostname and service name: | |||
RemoteSpecifier := NewRemoteEndpoint() | RemoteSpecifier := NewRemoteEndpoint() | |||
RemoteSpecifier.WithHostname("example.com") | RemoteSpecifier.WithHostname("example.com") | |||
RemoteSpecifier.WithService("https") | RemoteSpecifier.WithService("https") | |||
Specify a Remote Endpoint using an IPv6 address and remote port: | Specify a Remote Endpoint using an IPv6 address and remote port: | |||
RemoteSpecifier := NewRemoteEndpoint() | RemoteSpecifier := NewRemoteEndpoint() | |||
skipping to change at page 16, line 30 ¶ | skipping to change at page 18, line 52 ¶ | |||
Specify a Local Endpoint using a local interface name and local port: | Specify a Local Endpoint using a local interface name and local port: | |||
LocalSpecifier := NewLocalEndpoint() | LocalSpecifier := NewLocalEndpoint() | |||
LocalSpecifier.WithInterface("en0") | LocalSpecifier.WithInterface("en0") | |||
LocalSpecifier.WithPort(443) | LocalSpecifier.WithPort(443) | |||
As an alternative to specifying an interface name for the Local | As an alternative to specifying an interface name for the Local | |||
Endpoint, an application can express more fine-grained preferences | Endpoint, an application can express more fine-grained preferences | |||
using the "Interface Instance or Type" Selection Property, see | using the "Interface Instance or Type" Selection Property, see | |||
Section 5.2.10. However, if the application specifies Selection | Section 5.2.11. However, if the application specifies Selection | |||
Properties which are inconsistent with the Local Endpoint, this will | Properties that are inconsistent with the Local Endpoint, this will | |||
result in an error once the application attempts to open a | result in an Error once the application attempts to open a | |||
Connection. | Connection. | |||
Specify a Local Endpoint using a STUN server: | Specify a Local Endpoint using a STUN server: | |||
LocalSpecifier := NewLocalEndpoint() | LocalSpecifier := NewLocalEndpoint() | |||
LocalSpecifier.WithStunServer(address, port, credentials) | LocalSpecifier.WithStunServer(address, port, credentials) | |||
Specify a Local Endpoint using a Any-Source Multicast group to join | Specify a Local Endpoint using a Any-Source Multicast group to join | |||
on a named local interface: | on a named local interface: | |||
skipping to change at page 17, line 12 ¶ | skipping to change at page 19, line 30 ¶ | |||
Source-Specific Multicast requires setting both a Local and Remote | Source-Specific Multicast requires setting both a Local and Remote | |||
Endpoint: | Endpoint: | |||
LocalSpecifier := NewLocalEndpoint() | LocalSpecifier := NewLocalEndpoint() | |||
LocalSpecifier.WithIPv4Address(232.1.1.1) | LocalSpecifier.WithIPv4Address(232.1.1.1) | |||
LocalSpecifier.WithInterface("en0") | LocalSpecifier.WithInterface("en0") | |||
RemoteSpecifier := NewRemoteEndpoint() | RemoteSpecifier := NewRemoteEndpoint() | |||
RemoteSpecifier.WithIPv4Address(192.0.2.22) | RemoteSpecifier.WithIPv4Address(192.0.2.22) | |||
Implementations may also support additional endpoint representations | ||||
and provide a single NewEndpoint() call that takes different endpoint | ||||
representations. | ||||
Multiple endpoint identifiers can be specified for each Local | ||||
Endpoint and Remote Endpoint. For example, a Local Endpoint could be | ||||
configured with two interface names, or a Remote Endpoint could be | ||||
specified via both IPv4 and IPv6 addresses. These multiple | ||||
identifiers refer to the same transport endpoint. | ||||
The transport services API resolves names internally, when the | ||||
Initiate(), Listen(), or Rendezvous() method is called to establish a | ||||
Connection. The API explicitly does not require the application to | ||||
resolve names, though there is a tradeoff between early and late | ||||
binding of addresses to names. Early binding allows the API | ||||
implementation to reduce connection setup latency, at the cost of | ||||
potentially limited scope for alternate path discovery during | ||||
Connection establishment, as well as potential additional information | ||||
leakage about application interest when used with a resolution method | ||||
(such as DNS without TLS) which does not protect query | ||||
confidentiality. | ||||
The Resolve() action on Preconnection can be used by the application | ||||
to force early binding when required, for example with some Network | ||||
Address Translator (NAT) traversal protocols (see Section 6.3). | ||||
Specifying a multicast group address on the Local Endpoint will | ||||
indicate to the transport system that the resulting connection will | ||||
be used to receive multicast messages. The Remote Endpoint can be | ||||
used to filter by specific senders. This will restrict the | ||||
application to establishing the Preconnection by calling Listen(). | ||||
The accepted Connections are receive-only. | ||||
Similarly, specifying a multicast group address on the Remote | ||||
Endpoint will indicate that the resulting connection will be used to | ||||
send multicast messages. | ||||
5.2. Specifying Transport Properties | 5.2. Specifying Transport Properties | |||
A Preconnection Object holds properties reflecting the application's | A Preconnection Object holds properties reflecting the application's | |||
requirements and preferences for the transport. These include | requirements and preferences for the transport. These include | |||
Selection Properties for selecting protocol stacks and paths, as well | Selection Properties for selecting protocol stacks and paths, as well | |||
as Connection Properties for configuration of the detailed operation | as Connection Properties for configuration of the detailed operation | |||
of the selected Protocol Stacks. | of the selected Protocol Stacks. | |||
The protocol(s) and path(s) selected as candidates during | The protocol(s) and path(s) selected as candidates during | |||
establishment are determined and configured using these properties. | establishment are determined and configured using these properties. | |||
Since there could be paths over which some transport protocols are | Since there could be paths over which some transport protocols are | |||
unable to operate, or remote endpoints that support only specific | unable to operate, or remote endpoints that support only specific | |||
network addresses or transports, transport protocol selection is | network addresses or transports, transport protocol selection is | |||
necessarily tied to path selection. This may involve choosing | necessarily tied to path selection. This may involve choosing | |||
between multiple local interfaces that are connected to different | between multiple local interfaces that are connected to different | |||
access networks. | access networks. | |||
Most Selection Properties are represented as preferences, which can | Most Selection Properties are represented as preferences, which can | |||
have one of five preference levels: | have one of five preference levels: | |||
+------------+------------------------------------------------------+ | +============+========================================+ | |||
| Preference | Effect | | | Preference | Effect | | |||
+------------+------------------------------------------------------+ | +============+========================================+ | |||
| Require | Select only protocols/paths providing the property, | | | Require | Select only protocols/paths providing | | |||
| | fail otherwise | | | | the property, fail otherwise | | |||
| | | | +------------+----------------------------------------+ | |||
| Prefer | Prefer protocols/paths providing the property, | | | Prefer | Prefer protocols/paths providing the | | |||
| | proceed otherwise | | | | property, proceed otherwise | | |||
| | | | +------------+----------------------------------------+ | |||
| Ignore | No preference | | | Ignore | No preference | | |||
| | | | +------------+----------------------------------------+ | |||
| Avoid | Prefer protocols/paths not providing the property, | | | Avoid | Prefer protocols/paths not providing | | |||
| | proceed otherwise | | | | the property, proceed otherwise | | |||
| | | | +------------+----------------------------------------+ | |||
| Prohibit | Select only protocols/paths not providing the | | | Prohibit | Select only protocols/paths not | | |||
| | property, fail otherwise | | | | providing the property, fail otherwise | | |||
+------------+------------------------------------------------------+ | +------------+----------------------------------------+ | |||
Table 1: Selection Property Preference Levels | ||||
In addition, the pseudo-level "Default" can be used to reset the | In addition, the pseudo-level "Default" can be used to reset the | |||
property to the default level used by the implementation. This level | property to the default level used by the implementation. This level | |||
will never show up when queuing the value of a preference - the | will never show up when querying the value of a preference: the | |||
effective preference must be returned instead. | effective preference must be returned instead. | |||
The implementation MUST ensure an outcome that is consistent with | The implementation MUST ensure an outcome that is consistent with all | |||
application requirements as expressed using Require and Prohibit. | application requirements expressed using Require and Prohibit. While | |||
While preferences expressed using Prefer and Avoid influence protocol | preferences expressed using Prefer and Avoid influence protocol and | |||
and path selection as well, outcomes may vary given the same | path selection as well, outcomes can vary given the same Selection | |||
Selection Properties, as the available protocols and paths may vary | Properties, because the available protocols and paths can differ | |||
across systems and contexts. However, implementations are | across systems and contexts. However, implementations are | |||
RECOMMENDED to aim to provide a consistent outcome to an application, | RECOMMENDED to seek to provide a consistent outcome to an | |||
given the same Selection Properties. | application, given the same set of Selection Properties. | |||
Note that application preferences may conflict with each other. For | Note that application preferences can conflict with each other. For | |||
example, if an application indicates a preference for a specific path | example, if an application indicates a preference for a specific path | |||
by specifying an interface, but also a preference for a protocol, a | by specifying an interface, but also a preference for a protocol, a | |||
situation might occur in which the preferred protocol is not | situation might occur in which the preferred protocol is not | |||
available on the preferred path. In such cases, implementations | available on the preferred path. In such cases, implementations | |||
SHOULD prioritize Selection Properties that select paths over those | SHOULD prioritize Selection Properties that select paths over those | |||
that select protocols. Therefore, the transport system SHOULD race | that select protocols. Therefore, the transport system SHOULD race | |||
the path first, ignoring the protocol preference if the protocol does | the path first, ignoring the protocol preference if a specific | |||
not work on the path. | protocol does not work on the path. | |||
Selection and Connection Properties, as well as defaults for Message | Selection and Connection Properties, as well as defaults for Message | |||
Properties, can be added to a Preconnection to configure the | Properties, can be added to a Preconnection to configure the | |||
selection process and to further configure the eventually selected | selection process and to further configure the eventually selected | |||
protocol stack(s). They are collected into a TransportProperties | protocol stack(s). They are collected into a TransportProperties | |||
object to be passed into a Preconnection object: | object to be passed into a Preconnection object: | |||
TransportProperties := NewTransportProperties() | TransportProperties := NewTransportProperties() | |||
Individual properties are then added to the TransportProperties | Individual properties are then set on the TransportProperties Object. | |||
Object: | Setting a Transport Property to a value overrides the previous value | |||
of this Transport Property. | ||||
TransportProperties.Add(property, value) | TransportProperties.Set(property, value) | |||
Selection Properties of type "Preference" can be frequently used. | Selection Properties of type "Preference" might often be frequently | |||
Implementations MAY therefore provide additional convenience | used. Implementations MAY therefore provide additional convenience | |||
functions, see Appendix A.1 for examples. In addition, | functions to simplify use, see Appendix A.1 for examples. In | |||
implementations MAY provide a mechanism to create TransportProperties | addition, implementations MAY provide a mechanism to create | |||
objects that are preconfigured for common use cases as outlined in | TransportProperties objects that are preconfigured for common use | |||
Appendix A.2. | cases as outlined in Appendix A.2. | |||
For an existing Connection, the Transport Properties can be queried | For an existing Connection, the Transport Properties can be queried | |||
any time by using the following call on the Connection Object: | any time by using the following call on the Connection Object: | |||
TransportProperties := Connection.GetTransportProperties() | TransportProperties := Connection.GetTransportProperties() | |||
A Connection gets its Transport Properties either by being explicitly | A Connection gets its Transport Properties either by being explicitly | |||
configured via a Preconnection, by configuration after establishment, | configured via a Preconnection, by configuration after establishment, | |||
or by inheriting them from an antecedent via cloning; see Section 6.4 | or by inheriting them from an antecedent via cloning; see Section 6.4 | |||
for more. | for more. | |||
Section 7.1 provides a list of Connection Properties, while Selection | Section 7.1 provides a list of Connection Properties, while Selection | |||
Properties are listed in the subsections below. Note that many | Properties are listed in the subsections below. Many properties are | |||
properties are only considered during establishment, and can not be | only considered during establishment, and can not be changed after a | |||
changed after a Connection is established; however, they can be | Connection is established; however, they can still be queried. The | |||
queried. The return type of a queried Selection Property is Boolean, | return type of a queried Selection Property is Boolean, where "true" | |||
where "true" means that the Selection Property has been applied and | means that the Selection Property has been applied and "false" means | |||
"false" means that the Selection Property has not been applied. Note | that the Selection Property has not been applied. Note that "true" | |||
that "true" does not mean that a request has been honored. For | does not mean that a request has been honored. For example, if | |||
example, if "Congestion control" was requested with preference level | "Congestion control" was requested with preference level "Prefer", | |||
"Prefer", but congestion control could not be supported, querying the | but congestion control could not be supported, querying the | |||
"congestionControl" property yields the value "false". If preference | "congestionControl" property yields the value "false". If the | |||
level "Avoid" was used for "Congestion control", and, as requested, | preference level "Avoid" was used for "Congestion control", and, as | |||
the Connection is not congestion controlled, querying the | requested, the Connection is not congestion controlled, querying the | |||
"congestionControl" property also yields the value "false". | "congestionControl" property also yields the value "false". | |||
An implementation of this interface must provide sensible defaults | An implementation of this interface must provide sensible defaults | |||
for Selection Properties. The recommended default values for each | for Selection Properties. The recommended default values for each | |||
property below represent a configuration that can be implemented over | property below represent a configuration that can be implemented over | |||
TCP. If these default values are used and TCP is not supported by a | TCP. If these default values are used and TCP is not supported by a | |||
Transport Services implementation, then an application using the | Transport Services implementation, then an application using the | |||
default set of Properties might not succeed in establishing a | default set of Properties might not succeed in establishing a | |||
connection. Using the same default values for independent Transport | connection. Using the same default values for independent Transport | |||
Services implementations can be beneficical when application are | Services implementations can be beneficial when applications are | |||
ported between different implementations, even if this default could | ported between different implementations/platforms, even if this | |||
lead to a connection failure, as, for example, an application needs | default could lead to a connection failure when TCP is not available. | |||
to be explicitly designed to support a connectionless mode. In this | If default values other than those recommended below are used, it is | |||
case the application can regonize the failure and explicitly specify | recommended to clearly document any differences. | |||
a different set of Protocol Selection Properties that result in a | ||||
usable protocol. If default values other than those recommended | ||||
below are used, it is recommended to clearly document the | ||||
differences. | ||||
5.2.1. Reliable Data Transfer (Connection) | 5.2.1. Reliable Data Transfer (Connection) | |||
Name: reliability | Name: reliability | |||
Type: Preference | Type: Preference | |||
Default: Require | Default: Require | |||
This property specifies whether the application needs to use a | This property specifies whether the application needs to use a | |||
transport protocol that ensures that all data is received on the | transport protocol that ensures that all data is received at the | |||
other side without corruption. This also entails being notified when | Remote Endpoint without corruption. When reliable data transfer is | |||
a Connection is closed or aborted when reliable data transfer is | enabled, this also entails being notified when a Connection is closed | |||
enabled. | or aborted. | |||
5.2.2. Preservation of Message Boundaries | 5.2.2. Preservation of Message Boundaries | |||
Name: preserveMsgBoundaries | Name: preserveMsgBoundaries | |||
Type: Preference | Type: Preference | |||
Default: Prefer | Default: Prefer | |||
This property specifies whether the application needs or prefers to | This property specifies whether the application needs or prefers to | |||
use a transport protocol that preserves message boundaries. | use a transport protocol that preserves message boundaries. | |||
5.2.3. Configure Per-Message Reliability | 5.2.3. Configure Per-Message Reliability | |||
Name: perMsgReliability | Name: perMsgReliability | |||
Type: Preference | Type: Preference | |||
skipping to change at page 21, line 42 ¶ | skipping to change at page 23, line 29 ¶ | |||
5.2.5. Use 0-RTT Session Establishment with a Safely Replayable Message | 5.2.5. Use 0-RTT Session Establishment with a Safely Replayable Message | |||
Name: zeroRttMsg | Name: zeroRttMsg | |||
Type: Preference | Type: Preference | |||
Default: Ignore | Default: Ignore | |||
This property specifies whether an application would like to supply a | This property specifies whether an application would like to supply a | |||
Message to the transport protocol before Connection establishment, | Message to the transport protocol before Connection establishment | |||
which will then be reliably transferred to the other side before or | that will then be reliably transferred to the other side before or | |||
during Connection establishment, potentially multiple times (i.e., | during Connection establishment. This Message can potentially be | |||
multiple copies of the message data may be passed to the Remote | received multiple times (i.e., multiple copies of the message data | |||
Endpoint). See also Section 8.1.3.4. Note that disabling this | may be passed to the Remote Endpoint). See also Section 8.1.3.4. | |||
property has no effect for protocols that are not connection-oriented | Note that disabling this property has no effect for protocols that | |||
and do not protect against duplicated messages, e.g., UDP. | are not connection-oriented and do not protect against duplicated | |||
messages, e.g., UDP. | ||||
5.2.6. Multistream Connections in Group | 5.2.6. Multistream Connections in Group | |||
Name: multistreaming | Name: multistreaming | |||
Type: Preference | Type: Preference | |||
Default: Prefer | Default: Prefer | |||
This property specifies that the application would prefer multiple | This property specifies that the application would prefer multiple | |||
skipping to change at page 22, line 25 ¶ | skipping to change at page 24, line 13 ¶ | |||
single underlying transport connection where possible. | single underlying transport connection where possible. | |||
5.2.7. Full Checksum Coverage on Sending | 5.2.7. Full Checksum Coverage on Sending | |||
Name: perMsgChecksumLenSend | Name: perMsgChecksumLenSend | |||
Type: Preference | Type: Preference | |||
Default: Require | Default: Require | |||
This property specifies whether the application desires protection | This property specifies the application's need for protection against | |||
against corruption for all data transmitted on this Connection. | corruption for all data transmitted on this Connection. Disabling | |||
Disabling this property may enable to control checksum coverage later | this property could enable later control of the sender checksum | |||
(see Section 8.1.3.6). | coverage (see Section 8.1.3.6). | |||
5.2.8. Full Checksum Coverage on Receiving | 5.2.8. Full Checksum Coverage on Receiving | |||
Name: perMsgChecksumLenRecv | Name: perMsgChecksumLenRecv | |||
Type: Preference | Type: Preference | |||
Default: Require | Default: Require | |||
This property specifies whether the application desires protection | This property specifies the application's need for protection against | |||
against corruption for all data received on this Connection. | corruption for all data received on this Connection. Disabling this | |||
property could enable later control of the required minimum receiver | ||||
checksum coverage (see Section 7.1.1). | ||||
5.2.9. Congestion control | 5.2.9. Congestion control | |||
Name: congestionControl | Name: congestionControl | |||
Type: Preference | Type: Preference | |||
Default: Require | Default: Require | |||
This property specifies whether the application would like the | This property specifies whether the application would like the | |||
Connection to be congestion controlled or not. Note that if a | Connection to be congestion controlled or not. Note that if a | |||
Connection is not congestion controlled, an application using such a | Connection is not congestion controlled, an application using such a | |||
Connection should itself perform congestion control in accordance | Connection SHOULD itself perform congestion control in accordance | |||
with [RFC2914]. Also note that reliability is usually combined with | with [RFC2914] or use a circuit breaker in accordance with [RFC8084], | |||
congestion control in protocol implementations, rendering "reliable | whichever is appropriate. Also note that reliability is usually | |||
but not congestion controlled" a request that is unlikely to succeed. | combined with congestion control in protocol implementations, | |||
rendering "reliable but not congestion controlled" a request that is | ||||
unlikely to succeed. If the Connection is congestion controlled, | ||||
performing additional congestion control in the application can have | ||||
negative performance implications. | ||||
5.2.10. Interface Instance or Type | 5.2.10. Keep alive | |||
Name: keepAlive | ||||
Type: Preference | ||||
Default: Ignore | ||||
This property specifies whether the application would like the | ||||
Connection to send keep-alive packets or not. Note that if a | ||||
Connection determines that keep-alive packets are being sent, the | ||||
applicaton should itself avoid generating additional keep alive | ||||
messages. Note that when supported, the system will use the default | ||||
period for generation of the keep alive-packets. (See also | ||||
Section 7.1.4). | ||||
5.2.11. Interface Instance or Type | ||||
Name: interface | Name: interface | |||
Type: Set (Preference, Enumeration) | Type: Collection of (Preference, Enumeration) | |||
Default: Empty set (not setting a preference for any interface) | Default: Empty (not setting a preference for any interface) | |||
This property allows the application to select which specific network | This property allows the application to select any specific network | |||
interfaces or categories of interfaces it wants to "Require", | interfaces or categories of interfaces it wants to "Require", | |||
"Prohibit", "Prefer", or "Avoid". Note that marking a specific | "Prohibit", "Prefer", or "Avoid". Note that marking a specific | |||
interface as "Require" strictly limits path selection to a single | interface as "Require" strictly limits path selection to that single | |||
interface, and may often lead to less flexible and resilient | interface, and often leads to less flexible and resilient connection | |||
connection establishment. | establishment. | |||
In contrast to other Selection Properties, this property is a tuple | In contrast to other Selection Properties, this property is a tuple | |||
of an (Enumerated) interface identifier and a preference, and can | of an (Enumerated) interface identifier and a preference, and can | |||
either be implemented directly as such, or for making one preference | either be implemented directly as such, or for making one preference | |||
available for each interface and interface type available on the | available for each interface and interface type available on the | |||
system. | system. | |||
The set of valid interface types is implementation- and system- | The set of valid interface types is implementation- and system- | |||
specific. For example, on a mobile device, there may be "Wi-Fi" and | specific. For example, on a mobile device, there may be "Wi-Fi" and | |||
"Cellular" interface types available; whereas on a desktop computer, | "Cellular" interface types available; whereas on a desktop computer, | |||
there may be "Wi-Fi" and "Wired Ethernet" interface types available. | "Wi-Fi" and "Wired Ethernet" interface types might be available. An | |||
An implementation should provide all types that are supported on the | implementation should provide all types that are supported on the | |||
local system to all remote systems, to allow applications to be | local system to all remote systems, to allow applications to be | |||
written generically. For example, if a single implementation is used | written generically. For example, if a single implementation is used | |||
on both mobile devices and desktop devices, it should define the | on both mobile devices and desktop devices, it should define the | |||
"Cellular" interface type for both systems, since an application may | "Cellular" interface type for both systems, since an application | |||
want to always "Prohibit Cellular". | might wish to always prohibit cellular. | |||
The set of interface types is expected to change over time as new | The set of interface types is expected to change over time as new | |||
access technologies become available. The taxonomy of interface | access technologies become available. The taxonomy of interface | |||
types on a given Transport Services system is implementation- | types on a given Transport Services system is implementation- | |||
specific. | specific. | |||
Interface types should not be treated as a proxy for properties of | Interface types should not be treated as a proxy for properties of | |||
interfaces such as metered or unmetered network access. If an | interfaces such as metered or unmetered network access. If an | |||
application needs to prohibit metered interfaces, this should be | application needs to prohibit metered interfaces, this should be | |||
specified via Provisioning Domain attributes (see Section 5.2.11) or | specified via Provisioning Domain attributes (see Section 5.2.12) or | |||
another specific property. | another specific property. | |||
5.2.11. Provisioning Domain Instance or Type | 5.2.12. Provisioning Domain Instance or Type | |||
Name: pvd | Name: pvd | |||
Type: Set (Preference, Enumeration) | Type: Collection of (Preference, Enumeration) | |||
Default: Empty set (not setting a preference for any PvD) | Default: Empty (not setting a preference for any PvD) | |||
Similar to interface instances and types (see Section 5.2.10), this | Similar to interface instances and types (see Section 5.2.11), this | |||
property allows the application to control path selection by | property allows the application to control path selection by | |||
selecting which specific Provisioning Domains or categories of | selecting which specific Provisioning Domain (PvD) or categories of | |||
Provisioning Domains it wants to "Require", "Prohibit", "Prefer", or | PVDs it wants to "Require", "Prohibit", "Prefer", or "Avoid". | |||
"Avoid". Provisioning Domains define consistent sets of network | Provisioning Domains define consistent sets of network properties | |||
properties that may be more specific than network interfaces | that may be more specific than network interfaces [RFC7556]. | |||
[RFC7556]. | ||||
As with interface instances and types, this property is a tuple of an | As with interface instances and types, this property is a tuple of an | |||
(Enumerated) PvD identifier and a preference, and can either be | (Enumerated) PvD identifier and a preference, and can either be | |||
implemented directly as such, or for making one preference available | implemented directly as such, or for making one preference available | |||
for each interface and interface type available on the system. | for each interface and interface type available on the system. | |||
The identification of a specific Provisioning Domain (PvD) is defined | The identification of a specific PvD is implementation- and system- | |||
to be implementation- and system-specific, since there is not a | specific, because there is currently no portable standard format for | |||
portable standard format for a PvD identifier. For example, this | a PvD identifier. For example, this identifier might be a string | |||
identifier may be a string name or an integer. As with requiring | name or an integer. As with requiring specific interfaces, requiring | |||
specific interfaces, requiring a specific PvD strictly limits path | a specific PvD strictly limits the path selection. | |||
selection. | ||||
Categories or types of PvDs are also defined to be implementation- | Categories or types of PvDs are also defined to be implementation- | |||
and system-specific. These may be useful to identify a service that | and system-specific. These can be useful to identify a service that | |||
is provided by a PvD. For example, if an application wants to use a | is provided by a PvD. For example, if an application wants to use a | |||
PvD that provides a Voice-Over-IP service on a Cellular network, it | PvD that provides a Voice-Over-IP service on a Cellular network, it | |||
can use the relevant PvD type to require some PvD that provides this | can use the relevant PvD type to require a PvD that provides this | |||
service, without needing to look up a particular instance. While | service, without needing to look up a particular instance. While | |||
this does restrict path selection, it is broader than requiring | this does restrict path selection, it is broader than requiring | |||
specific PvD instances or interface instances, and should be | specific PvD instances or interface instances, and should be | |||
preferred over these options. | preferred over these options. | |||
5.2.12. Use Temporary Local Address | 5.2.13. Use Temporary Local Address | |||
Name: useTemporaryLocalAddress | Name: useTemporaryLocalAddress | |||
Type: Preference | Type: Preference | |||
Default: Avoid for Listeners and Rendezvous Connections. Prefer for | Default: Avoid for Listeners and Rendezvous Connections. Prefer for | |||
other Connections. | other Connections. | |||
This property allows the application to express a preference for the | This property allows the application to express a preference for the | |||
use of temporary local addresses, sometimes called "privacy" | use of temporary local addresses, sometimes called "privacy" | |||
addresses [RFC4941]. Temporary addresses are generally used to | addresses [RFC4941]. Temporary addresses are generally used to | |||
prevent linking connections over time when a stable address, | prevent linking connections over time when a stable address, | |||
sometimes called "permanent" address, is not needed. Note that if an | sometimes called "permanent" address, is not needed. There are some | |||
caveats to note when specifying this property. First, if an | ||||
application Requires the use of temporary addresses, the resulting | application Requires the use of temporary addresses, the resulting | |||
Connection cannot use IPv4, as temporary addresses do not exist in | Connection cannot use IPv4, because temporary addresses do not exist | |||
IPv4. | in IPv4. Second, temporary local addresses might involve trading off | |||
privacy for performance. For instance, temporary addresses can | ||||
interfere with resumption mechanisms that some protocols rely on to | ||||
reduce initial latency. | ||||
5.2.13. Multi-Paths Transport | 5.2.14. Multi-Paths Transport | |||
Name: multipath | Name: multipath | |||
Type: Enumeration | Type: Enumeration | |||
Default: Disabled for connections created through initiate and | Default: Disabled for connections created through initiate and | |||
rendezvous, Passive for listeners | rendezvous, Passive for listeners | |||
This property specifies whether and how applications want to take | This property specifies whether and how applications want to take | |||
advantage of transferring data across multiple paths between the same | advantage of transferring data across multiple paths between the same | |||
skipping to change at page 25, line 43 ¶ | skipping to change at page 28, line 9 ¶ | |||
Active: The connection will negotiate the use of multiple paths if | Active: The connection will negotiate the use of multiple paths if | |||
the chosen transport supports this. | the chosen transport supports this. | |||
Passive: The connection will support the use of multiple paths if | Passive: The connection will support the use of multiple paths if | |||
the remote endpoint requests it. | the remote endpoint requests it. | |||
The policy for using multiple paths is specified using the separate | The policy for using multiple paths is specified using the separate | |||
"multipath-policy" property, see Section 7.1.7 below. To enable the | "multipath-policy" property, see Section 7.1.7 below. To enable the | |||
peer endpoint to initiate additional paths towards a local address | peer endpoint to initiate additional paths towards a local address | |||
other than the one initially used, it is necessary to set the | other than the one initially used, it is necessary to set the | |||
Alternative Addresses property (see Section 5.2.14 below). | Alternative Addresses property (see Section 5.2.15 below). | |||
Setting this property to "Active", may have privacy implications: It | Setting this property to "Active", can have privacy implications: It | |||
enables the transport to establish connectivity using alternate paths | enables the transport to establish connectivity using alternate paths | |||
that may make users linkable across multiple paths, even if the | that might result in users being linkable across the multiple paths, | |||
Advertisement of Alternative Addresses property (see Section 5.2.14 | even if the Advertisement of Alternative Addresses property (see | |||
below) is set to false. | Section 5.2.15 below) is set to false. | |||
Enumeration values other than "Disabled" are interpreted as a | Enumeration values other than "Disabled" are interpreted as a | |||
preference for choosing protocols that can make use of multiple | preference for choosing protocols that can make use of multiple | |||
paths. The "Disabled" value implies a requirement not to use | paths. The "Disabled" value implies a requirement not to use | |||
multiple paths in parallel but does not prevent choosing a protocol | multiple paths in parallel but does not prevent choosing a protocol | |||
that is capable of using multiple paths, e.g., it does not prevent | that is capable of using multiple paths, e.g., it does not prevent | |||
choosing TCP, but prevents sending the "MP_CAPABLE" option in the TCP | choosing TCP, but prevents sending the "MP_CAPABLE" option in the TCP | |||
handshake. | handshake. | |||
5.2.14. Advertisement of Alternative Addresses | 5.2.15. Advertisement of Alternative Addresses | |||
Name: advertises-altaddr | Name: advertises-altaddr | |||
Type: Boolean | Type: Boolean | |||
Default: False | Default: False | |||
This property specifies whether alternative addresses, e.g., of other | This property specifies whether alternative addresses, e.g., of other | |||
interfaces, should be advertised to the peer endpoint by the protocol | interfaces, should be advertised to the peer endpoint by the protocol | |||
stack. Advertising these addresses enables the peer-endpoint to | stack. Advertising these addresses enables the peer-endpoint to | |||
establish additional connectivity, e.g., for connection migration or | establish additional connectivity, e.g., for connection migration or | |||
using multiple paths. | using multiple paths. | |||
Note that this may have privacy implications because it may make | Note that this can have privacy implications because it might result | |||
users linkable across multiple paths. Also, note that setting this | in users being linkable across the multiple paths. Also, note that | |||
to false does not prevent the local transport system from | setting this to false does not prevent the local transport system | |||
_establishing_ connectivity using alternate paths (see Section 5.2.13 | from _establishing_ connectivity using alternate paths (see | |||
above); it only prevents _procative advertisement_ of addresses. | Section 5.2.14 above); it only prevents _proactive advertisement_ of | |||
addresses. | ||||
5.2.15. Direction of communication | 5.2.16. Direction of communication | |||
Name: direction | Name: direction | |||
Type: Enumeration | Type: Enumeration | |||
Default: Bidirectional | Default: Bidirectional | |||
This property specifies whether an application wants to use the | This property specifies whether an application wants to use the | |||
connection for sending and/or receiving data. Possible values are: | connection for sending and/or receiving data. Possible values are: | |||
Bidirectional: The connection must support sending and receiving | Bidirectional: The connection must support sending and receiving | |||
data | data | |||
Unidirectional send: The connection must support sending data, and | Unidirectional send: The connection must support sending data, and | |||
the application cannot use the connection to receive any data | the application cannot use the connection to receive any data | |||
Unidirectional receive: The connection must support receiving data, | Unidirectional receive: The connection must support receiving data, | |||
skipping to change at page 27, line 7 ¶ | skipping to change at page 29, line 21 ¶ | |||
the application cannot use the connection to receive any data | the application cannot use the connection to receive any data | |||
Unidirectional receive: The connection must support receiving data, | Unidirectional receive: The connection must support receiving data, | |||
and the application cannot use the connection to send any data | and the application cannot use the connection to send any data | |||
Since unidirectional communication can be supported by transports | Since unidirectional communication can be supported by transports | |||
offering bidirectional communication, specifying unidirectional | offering bidirectional communication, specifying unidirectional | |||
communication may cause a transport stack that supports bidirectional | communication may cause a transport stack that supports bidirectional | |||
communication to be selected. | communication to be selected. | |||
5.2.16. Notification of excessive retransmissions | ||||
Name: retransmitNotify | ||||
Type: Preference | ||||
Default: Ignore | ||||
This property specifies whether an application considers it useful to | ||||
be informed in case sent data was retransmitted more often than a | ||||
certain threshold (see Section 7.1.1 for configuration of this | ||||
threshold). | ||||
5.2.17. Notification of ICMP soft error message arrival | 5.2.17. Notification of ICMP soft error message arrival | |||
Name: softErrorNotify | Name: softErrorNotify | |||
Type: Preference | Type: Preference | |||
Default: Ignore | Default: Ignore | |||
This property specifies whether an application considers it useful to | This property specifies whether an application considers it useful to | |||
be informed when an ICMP error message arrives that does not force | be informed when an ICMP error message arrives that does not force | |||
termination of a connection. When set to true, received ICMP errors | termination of a connection. When set to true, received ICMP errors | |||
will be available as SoftErrors, see Section 7.3.1. Note that even | are available as SoftErrors, see Section 7.3.1. Note that even if a | |||
if a protocol supporting this property is selected, not all ICMP | protocol supporting this property is selected, not all ICMP errors | |||
errors will necessarily be delivered, so applications cannot rely on | will necessarily be delivered, so applications cannot rely upon | |||
receiving them. | receiving them [RFC8085]. | |||
5.2.18. Initiating side is not the first to write | 5.2.18. Initiating side is not the first to write | |||
Name: activeReadBeforeSend | Name: activeReadBeforeSend | |||
Type: Preference | Type: Preference | |||
Default: Ignore | Default: Ignore | |||
The most common client-server communication pattern involves the | The most common client-server communication pattern involves the | |||
skipping to change at page 28, line 13 ¶ | skipping to change at page 30, line 14 ¶ | |||
establishing connections using Rendezvous(). Requiring this property | establishing connections using Rendezvous(). Requiring this property | |||
limits the choice of mappings to underlying protocols, which can | limits the choice of mappings to underlying protocols, which can | |||
reduce efficiency. For example, it prevents the transport system | reduce efficiency. For example, it prevents the transport system | |||
from mapping Connections to SCTP streams, where the first transmitted | from mapping Connections to SCTP streams, where the first transmitted | |||
data takes the role of an active open signal [I-D.ietf-taps-impl]. | data takes the role of an active open signal [I-D.ietf-taps-impl]. | |||
5.3. Specifying Security Parameters and Callbacks | 5.3. Specifying Security Parameters and Callbacks | |||
Most security parameters, e.g., TLS ciphersuites, local identity and | Most security parameters, e.g., TLS ciphersuites, local identity and | |||
private key, etc., may be configured statically. Others are | private key, etc., may be configured statically. Others are | |||
dynamically configured during connection establishment. Thus, we | dynamically configured during connection establishment. Security | |||
partition security parameters and callbacks based on their place in | parameters and callbacks are partitioned based on their place in the | |||
the lifetime of connection establishment. Similar to Transport | lifetime of connection establishment. Similar to Transport | |||
Properties, both parameters and callbacks are inherited during | Properties, both parameters and callbacks are inherited during | |||
cloning (see Section 6.4). | cloning (see Section 6.4). | |||
5.3.1. Pre-Connection Parameters | 5.3.1. Pre-Connection Parameters | |||
Common parameters such as TLS ciphersuites are known to | Common parameters such as TLS ciphersuites are known to | |||
implementations. Clients should use common safe defaults for these | implementations. Clients should use common safe defaults for these | |||
values whenever possible. However, as discussed in | values whenever possible. However, as discussed in [RFC8922], many | |||
[I-D.ietf-taps-transport-security], many transport security protocols | transport security protocols require specific security parameters and | |||
require specific security parameters and constraints from the client | constraints from the client at the time of configuration and actively | |||
at the time of configuration and actively during a handshake. These | during a handshake. These configuration parameters need to be | |||
configuration parameters need to be specified in the pre-connection | specified in the pre-connection phase and are created as follows: | |||
phase and are created as follows: | ||||
SecurityParameters := NewSecurityParameters() | SecurityParameters := NewSecurityParameters() | |||
Security configuration parameters and sample usage follow: | Security configuration parameters and sample usage follow: | |||
o Local identity and private keys: Used to perform private key | * Local identity and private keys: Used to perform private key | |||
operations and prove one's identity to the Remote Endpoint. | operations and prove one's identity to the Remote Endpoint. | |||
(Note, if private keys are not available, e.g., since they are | (Note, if private keys are not available, e.g., since they are | |||
stored in hardware security modules (HSMs), handshake callbacks | stored in hardware security modules (HSMs), handshake callbacks | |||
must be used. See below for details.) | must be used. See below for details.) | |||
SecurityParameters.Add('identity', identity) | SecurityParameters.Set('identity', identity) | |||
SecurityParameters.Add('keypair', privateKey, publicKey) | SecurityParameters.Set('keypair', privateKey, publicKey) | |||
o Supported algorithms: Used to restrict what parameters are used by | * Supported algorithms: Used to restrict what parameters are used by | |||
underlying transport security protocols. When not specified, | underlying transport security protocols. When not specified, | |||
these algorithms should use known and safe defaults for the | these algorithms should use known and safe defaults for the | |||
system. Parameters include: ciphersuites, supported groups, and | system. Parameters include: ciphersuites, supported groups, and | |||
signature algorithms. | signature algorithms. These parameters take a collection of | |||
supported algorithms as parameter. | ||||
SecurityParameters.Add('supported-group', 'secp256k1') | SecurityParameters.Set('supported-group', 'secp256k1') | |||
SecurityParameters.Add('ciphersuite, 'TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256') | SecurityParameters.Set('ciphersuite, 'TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256') | |||
SecurityParameters.Add('signature-algorithm', 'ed25519') | SecurityParameters.Set('signature-algorithm', 'ed25519') | |||
o Pre-Shared Key import: Used to install pre-shared keying material | ||||
* Pre-Shared Key import: Used to install pre-shared keying material | ||||
established out-of-band. Each pre-shared keying material is | established out-of-band. Each pre-shared keying material is | |||
associated with some identity that typically identifies its use or | associated with some identity that typically identifies its use or | |||
has some protocol-specific meaning to the Remote Endpoint. | has some protocol-specific meaning to the Remote Endpoint. | |||
SecurityParameters.Add('pre-shared-key', key, identity) | SecurityParameters.Set('pre-shared-key', key, identity) | |||
o Session cache management: Used to tune cache capacity, lifetime, | * Session cache management: Used to tune session cache capacity, | |||
re-use, and eviction policies, e.g., LRU or FIFO.may also me | lifetime, and other policies. | |||
changed, but are implementation-specific. | ||||
SecurityParameters.Set('max-cached-sessions', 16) | ||||
SecurityParameters.Set('cached-session-lifetime-seconds', 3600) | ||||
5.3.2. Connection Establishment Callbacks | 5.3.2. Connection Establishment Callbacks | |||
Security decisions, especially pertaining to trust, are not static. | Security decisions, especially pertaining to trust, are not static. | |||
Once configured, parameters may also be supplied during connection | Once configured, parameters may also be supplied during connection | |||
establishment. These are best handled as client-provided callbacks. | establishment. These are best handled as client-provided callbacks. | |||
Security handshake callbacks that may be invoked during connection | Security handshake callbacks that may be invoked during connection | |||
establishment include: | establishment include: | |||
o Trust verification callback: Invoked when a Remote Endpoint's | * Trust verification callback: Invoked when a Remote Endpoint's | |||
trust must be validated before the handshake protocol can | trust must be validated before the handshake protocol can | |||
continue. | continue. | |||
TrustCallback := NewCallback({ | TrustCallback := NewCallback({ | |||
// Handle trust, return the result | // Handle trust, return the result | |||
}) | }) | |||
SecurityParameters.SetTrustVerificationCallback(trustCallback) | SecurityParameters.SetTrustVerificationCallback(trustCallback) | |||
o Identity challenge callback: Invoked when a private key operation | * Identity challenge callback: Invoked when a private key operation | |||
is required, e.g., when local authentication is requested by a | is required, e.g., when local authentication is requested by a | |||
remote. | remote. | |||
ChallengeCallback := NewCallback({ | ChallengeCallback := NewCallback({ | |||
// Handle challenge | // Handle challenge | |||
}) | }) | |||
SecurityParameters.SetIdentityChallengeCallback(challengeCallback) | SecurityParameters.SetIdentityChallengeCallback(challengeCallback) | |||
6. Establishing Connections | 6. Establishing Connections | |||
Before a Connection can be used for data transfer, it must be | Before a Connection can be used for data transfer, it needs to be | |||
established. Establishment ends the pre-establishment phase; all | established. Establishment ends the pre-establishment phase; all | |||
transport properties and cryptographic parameter specification must | transport properties and cryptographic parameter specification must | |||
be complete before establishment, as these will be used to select | be complete before establishment, as these will be used to select | |||
candidate Paths and Protocol Stacks for the Connection. | candidate Paths and Protocol Stacks for the Connection. | |||
Establishment may be active, using the Initiate() Action; passive, | Establishment may be active, using the Initiate() Action; passive, | |||
using the Listen() Action; or simultaneous for peer-to-peer, using | using the Listen() Action; or simultaneous for peer-to-peer, using | |||
the Rendezvous() Action. These Actions are described in the | the Rendezvous() Action. These Actions are described in the | |||
subsections below. | subsections below. | |||
6.1. Active Open: Initiate | 6.1. Active Open: Initiate | |||
skipping to change at page 30, line 49 ¶ | skipping to change at page 33, line 14 ¶ | |||
The Ready Event occurs after Initiate has established a transport- | The Ready Event occurs after Initiate has established a transport- | |||
layer connection on at least one usable candidate Protocol Stack over | layer connection on at least one usable candidate Protocol Stack over | |||
at least one candidate Path. No Receive Events (see Section 8.3) | at least one candidate Path. No Receive Events (see Section 8.3) | |||
will occur before the Ready Event for Connections established using | will occur before the Ready Event for Connections established using | |||
Initiate. | Initiate. | |||
Connection -> EstablishmentError<reason?> | Connection -> EstablishmentError<reason?> | |||
An EstablishmentError occurs either when the set of transport | An EstablishmentError occurs either when the set of transport | |||
properties and security parameters cannot be fulfilled on a | properties and security parameters cannot be fulfilled on a | |||
Connection for initiation (e.g. the set of available Paths and/or | Connection for initiation (e.g., the set of available Paths and/or | |||
Protocol Stacks meeting the constraints is empty) or reconciled with | Protocol Stacks meeting the constraints is empty) or reconciled with | |||
the local and/or remote Endpoints; when the remote specifier cannot | the Local and/or Remote Endpoints; when the remote specifier cannot | |||
be resolved; or when no transport-layer connection can be established | be resolved; or when no transport-layer connection can be established | |||
to the remote Endpoint (e.g. because the remote Endpoint is not | to the Remote Endpoint (e.g., because the Remote Endpoint is not | |||
accepting connections, the application is prohibited from opening a | accepting connections, the application is prohibited from opening a | |||
Connection by the operating system, or the establishment attempt has | Connection by the operating system, or the establishment attempt has | |||
timed out for any other reason). | timed out for any other reason). | |||
See also Section 8.2.6 to combine Connection establishment and | Connection establishment and transmission of the first message can be | |||
transmission of the first message in a single action. | combined in a single action Section 8.2.5. | |||
6.2. Passive Open: Listen | 6.2. Passive Open: Listen | |||
Passive open is the Action of waiting for Connections from remote | Passive open is the Action of waiting for Connections from Remote | |||
Endpoints, commonly used by servers in client-server interactions. | Endpoints, commonly used by servers in client-server interactions. | |||
Passive open is supported by this interface through the Listen Action | Passive open is supported by this interface through the Listen Action | |||
and returns a Listener object: | and returns a Listener object: | |||
Listener := Preconnection.Listen() | Listener := Preconnection.Listen() | |||
Before calling Listen, the caller must have initialized the | Before calling Listen, the caller must have initialized the | |||
Preconnection during the pre-establishment phase with a Local | Preconnection during the pre-establishment phase with a Local | |||
Endpoint specifier, as well as all properties necessary for Protocol | Endpoint specifier, as well as all properties necessary for Protocol | |||
Stack selection. A Remote Endpoint may optionally be specified, to | Stack selection. A Remote Endpoint may optionally be specified, to | |||
constrain what Connections are accepted. | constrain what Connections are accepted. | |||
The Listen() Action returns a Listener object. Once Listen() has | The Listen() Action returns a Listener object. Once Listen() has | |||
been called, any changes to the Preconnection MUST NOT have any | been called, any changes to the Preconnection MUST NOT have any | |||
effect on the Listener. The Preconnection can be disposed of or | effect on the Listener. The Preconnection can be disposed of or | |||
reused, e.g., to create another Listener. | reused, e.g., to create another Listener. | |||
Listening continues until the global context shuts down, or until the | ||||
Stop action is performed on the Listener object: | ||||
Listener.Stop() | Listener.Stop() | |||
After Stop() is called, the Listener can be disposed of. | Listening continues until the global context shuts down, or until the | |||
Stop action is performed on the Listener object. | ||||
Listener -> ConnectionReceived<Connection> | Listener -> ConnectionReceived<Connection> | |||
The ConnectionReceived Event occurs when a Remote Endpoint has | The ConnectionReceived Event occurs when a Remote Endpoint has | |||
established a transport-layer connection to this Listener (for | established a transport-layer connection to this Listener (for | |||
Connection-oriented transport protocols), or when the first Message | Connection-oriented transport protocols), or when the first Message | |||
has been received from the Remote Endpoint (for Connectionless | has been received from the Remote Endpoint (for Connectionless | |||
protocols), causing a new Connection to be created. The resulting | protocols), causing a new Connection to be created. The resulting | |||
Connection is contained within the ConnectionReceived Event, and is | Connection is contained within the ConnectionReceived Event, and is | |||
ready to use as soon as it is passed to the application via the | ready to use as soon as it is passed to the application via the | |||
event. | event. | |||
Listener.SetNewConnectionLimit(value) | Listener.SetNewConnectionLimit(value) | |||
skipping to change at page 32, line 40 ¶ | skipping to change at page 35, line 7 ¶ | |||
the Rendezvous() Action: | the Rendezvous() Action: | |||
Preconnection.Rendezvous() | Preconnection.Rendezvous() | |||
The Preconnection Object must be specified with both a Local Endpoint | The Preconnection Object must be specified with both a Local Endpoint | |||
and a Remote Endpoint, and also the transport properties and security | and a Remote Endpoint, and also the transport properties and security | |||
parameters needed for Protocol Stack selection. | parameters needed for Protocol Stack selection. | |||
The Rendezvous() Action causes the Preconnection to listen on the | The Rendezvous() Action causes the Preconnection to listen on the | |||
Local Endpoint for an incoming Connection from the Remote Endpoint, | Local Endpoint for an incoming Connection from the Remote Endpoint, | |||
while simultaneously trying to establish a Connection from the Local | while also simultaneously trying to establish a Connection from the | |||
Endpoint to the Remote Endpoint. This corresponds to a TCP | Local Endpoint to the Remote Endpoint. | |||
simultaneous open, for example. | ||||
If there are multiple Local Endpoints or Remote Endpoints configured, | ||||
then initiating a rendezvous action will systematically probe the | ||||
reachability of those endpoints following an approach such as that | ||||
used in Interactive Connectivity Establishment (ICE) [RFC5245]. | ||||
If the endpoints are suspected to be behind a NAT, Rendezvous() can | ||||
be initiated using Local and Remote Endpoints that support a method | ||||
of discovering NAT bindings such as Session Traversal Utilities for | ||||
NAT (STUN) [RFC8489] or Traversal Using Relays around NAT (TURN) | ||||
[RFC5766]. In this case, the Local Endpoint will resolve to a | ||||
mixture of local and server reflexive addresses. The Resolve() | ||||
action on the Preconnection can be used to discover these bindings: | ||||
[]Preconnection := Preconnection.Resolve() | ||||
The Resolve() call returns a list of Preconnection Objects, that | ||||
represent the concrete addresses, local and server reflexive, on | ||||
which a Rendezvous() for the Preconnection will listen for incoming | ||||
Connections. These resolved Preconnections will share all other | ||||
Properties with the Preconnection from which they are derived, though | ||||
some Properties may be made more-specific by the resolution process. | ||||
An application that uses Rendezvous() to establish a peer-to-peer | ||||
connection in the presence of NATs will configure the Preconnection | ||||
object with a Local Endpoint that supports NAT binding discovery. It | ||||
will then Resolve() on that endpoint, and pass the resulting list of | ||||
candidate local addresses to the peer via a signalling protocol, for | ||||
example as part of an ICE [RFC5245] exchange within SIP [RFC3261] or | ||||
WebRTC [RFC7478]. The peer will, via the same signalling channel, | ||||
return the remote endpoint candidates. These remote endpoint | ||||
candidates are then configured on the Preconnection, allowing the | ||||
Rendezvous() Action to be initiated. | ||||
The Rendezvous() Action returns a Connection object. Once | The Rendezvous() Action returns a Connection object. Once | |||
Rendezvous() has been called, any changes to the Preconnection MUST | Rendezvous() has been called, any changes to the Preconnection MUST | |||
NOT have any effect on the Connection. However, the Preconnection | NOT have any effect on the Connection. However, the Preconnection | |||
can be reused, e.g., for Rendezvous of another Connection. | can be reused, e.g., for Rendezvous of another Connection. | |||
Preconnection -> RendezvousDone<Connection> | Preconnection -> RendezvousDone<Connection> | |||
The RendezvousDone<> Event occurs when a Connection is established | The RendezvousDone<> Event occurs when a Connection is established | |||
with the Remote Endpoint. For Connection-oriented transports, this | with the Remote Endpoint. For Connection-oriented transports, this | |||
occurs when the transport-layer connection is established; for | occurs when the transport-layer connection is established; for | |||
Connectionless transports, it occurs when the first Message is | Connectionless transports, it occurs when the first Message is | |||
received from the Remote Endpoint. The resulting Connection is | received from the Remote Endpoint. The resulting Connection is | |||
contained within the RendezvousDone<> Event, and is ready to use as | contained within the RendezvousDone<> Event, and is ready to use as | |||
soon as it is passed to the application via the Event. | soon as it is passed to the application via the Event. | |||
Preconnection -> EstablishmentError<reason?> | Preconnection -> EstablishmentError<reason?> | |||
skipping to change at page 33, line 38 ¶ | skipping to change at page 36, line 35 ¶ | |||
[]Preconnection := Preconnection.Resolve() | []Preconnection := Preconnection.Resolve() | |||
The Resolve() call returns a list of Preconnection Objects, that | The Resolve() call returns a list of Preconnection Objects, that | |||
represent the concrete addresses, local and server reflexive, on | represent the concrete addresses, local and server reflexive, on | |||
which a Rendezvous() for the Preconnection will listen for incoming | which a Rendezvous() for the Preconnection will listen for incoming | |||
Connections. These resolved Preconnections will share all other | Connections. These resolved Preconnections will share all other | |||
Properties with the Preconnection from which they are derived, though | Properties with the Preconnection from which they are derived, though | |||
some Properties may be made more-specific by the resolution process. | some Properties may be made more-specific by the resolution process. | |||
This list can be passed to a peer via a signalling protocol, such as | This list can be passed to a peer via a signalling protocol, such as | |||
SIP [RFC3261] or WebRTC [RFC7478], to configure the remote. | SIP [RFC3261] or WebRTC [RFC7478], to configure the remote endpoint. | |||
6.4. Connection Groups | 6.4. Connection Groups | |||
Entangled Connections can be created using the Clone Action: | Entangled Connections can be created using the Clone Action: | |||
Connection := Connection.Clone() | Connection := Connection.Clone() | |||
Calling Clone on a Connection yields a group of Connections: the | ||||
parent Connection on which Clone was called, and a resulting cloned | ||||
Connection. The connections within a group are "entangled" with each | ||||
other, and become part of a Connection Group. Calling Clone on any | ||||
of these Connections adds another Connection to the Connection Group, | ||||
and so on. "Entangled" Connections share all Connection Properties | ||||
except "Connection Priority" (see Section 7.1.2) . Like all other | ||||
Properties, Connection Priority is copied to the new Connection when | ||||
calling Clone(), but it is not entangled: Changing Connection | ||||
Priority on one Connection does not change it on the other | ||||
Connections in the same Connection Group. | ||||
Calling Clone on a Connection yields a group of two Connections: the | The stack of Message Framers associated with a Connection are also | |||
parent Connection on which Clone was called, and the resulting cloned | copied to the cloned Connection when calling Clone. In other words, | |||
Connection. These connections are "entangled" with each other, and | a cloned Connection has the same stack of Message Framers as the | |||
become part of a Connection Group. Calling Clone on any of these two | Connection from which they are Cloned, but these Framers may | |||
Connections adds a third Connection to the Connection Group, and so | internally maintain per-Connection state. | |||
on. Connections in a Connection Group generally share Connection | ||||
Properties. However, there may be exceptions, such as "Priority | ||||
(Connection)", see Section 7.1.3. Like all other Properties, | ||||
Priority is copied to the new Connection when calling Clone(), but it | ||||
is not entangled: Changing Priority on one Connection does not change | ||||
it on the other Connections in the same Connection Group. | ||||
It is also possible to check which Connections belong to the same | It is also possible to check which Connections belong to the same | |||
Connection Group. Calling GroupedConnections() on a specific | Connection Group. Calling GroupedConnections() on a specific | |||
Connection returns a set of all Connections in the same group. | Connection returns a set of all Connections in the same group. | |||
[]Connection := Connection.GroupedConnections() | []Connection := Connection.GroupedConnections() | |||
Connections will be in the same group if the application previously | Connections will belong to the same group if the application | |||
called Clone. Passive Connections can also be added to the same | previously called Clone. Passive Connections can also be added to | |||
group - e.g., when a Listener receives a new Connection that is just | the same group - e.g., when a Listener receives a new Connection that | |||
a new stream of an already active multi-streaming protocol instance. | is just a new stream of an already active multi-streaming protocol | |||
instance. | ||||
Changing one of the Connection Properties on one Connection in the | Changing one of the Connection Properties on one Connection in the | |||
group changes it for all others. Message Properties, however, are | group changes it for all others. Message Properties, however, are | |||
not entangled. For example, changing "Timeout for aborting | not entangled. For example, changing "Timeout for aborting | |||
Connection" (see Section 7.1.4) on one Connection in a group will | Connection" (see Section 7.1.3) on one Connection in a group will | |||
automatically change this Connection Property for all Connections in | automatically change this Connection Property for all Connections in | |||
the group in the same way. However, changing "Lifetime" (see | the group in the same way. However, changing "Lifetime" (see | |||
Section 8.1.3.1) of a Message will only affect a single Message on a | Section 8.1.3.1) of a Message will only affect a single Message on a | |||
single Connection, entangled or not. | single Connection, entangled or not. | |||
If the underlying protocol supports multi-streaming, it is natural to | If the underlying protocol supports multi-streaming, it is natural to | |||
use this functionality to implement Clone. In that case, entangled | use this functionality to implement Clone. In that case, entangled | |||
Connections are multiplexed together, giving them similar treatment | Connections are multiplexed together, giving them similar treatment | |||
not only inside endpoints but also across the end-to-end Internet | not only inside endpoints, but also across the end-to-end Internet | |||
path. | path. | |||
Note that calling Clone() may result in on-the-wire signaling, e.g., | Note that calling Clone() can result in on-the-wire signaling, e.g., | |||
to open a new connection, depending on the underlying Protocol Stack. | to open a new connection, depending on the underlying Protocol Stack. | |||
When Clone() leads to multiple connections being opened instead of | When Clone() leads to multiple connections being opened instead of | |||
multi-streaming, the transport system will ensure consistency of | multi-streaming, the transport system will ensure consistency of | |||
Connection Properties by uniformly applying them to all underlying | Connection Properties by uniformly applying them to all underlying | |||
connections in a group. Even in such a case, there are possibilities | connections in a group. Even in such a case, there are possibilities | |||
for a transport system to implement prioritization within a | for a transport system to implement prioritization within a | |||
Connection Group [TCP-COUPLING] [RFC8699]. | Connection Group [TCP-COUPLING] [RFC8699]. | |||
Attempts to clone a Connection can result in a CloneError: | Attempts to clone a Connection can result in a CloneError: | |||
Connection -> CloneError<reason?> | Connection -> CloneError<reason?> | |||
The Connection Property "Priority" operates on entangled Connections | The Connection Priority Connection Property operates on entangled | |||
as in Section 8.1.3.2: when allocating available network capacity | Connections using the same approach as in Section 8.1.3.2: when | |||
among Connections in a Connection Group, sends on Connections with | allocating available network capacity among Connections in a | |||
higher Priority values will be prioritized over sends on Connections | Connection Group, sends on Connections with lower Priority values | |||
with lower Priority values. A transport system implementation | will be prioritized over sends on Connections with higher Priority | |||
should, if possible, assign each Connection the capacity share (M-N) | values. Capacity will be shared among these Connections according to | |||
x C / M, where N is the Connection's Priority value, M is the maximum | the Connection Group Transmission Scheduler property (Section 7.1.5). | |||
Priority value used by all Connections in the group and C is the | See Section 8.2.6 for more. | |||
total available capacity. However, the Priority setting is purely | ||||
advisory, and no guarantees are given about the way capacity is | ||||
shared. Each implementation is free to implement a way to share | ||||
capacity that it sees fit. | ||||
7. Managing Connections | 7. Managing Connections | |||
During pre-establishment and after establishment, connections can be | During pre-establishment and after establishment, connections can be | |||
configured and queried using Connection Properties, and asynchronous | configured and queried using Connection Properties, and asynchronous | |||
information may be available about the state of the connection via | information may be available about the state of the connection via | |||
Soft Errors. | Soft Errors. | |||
Connection Properties represent the configuration and state of the | Connection Properties represent the configuration and state of the | |||
selected Protocol Stack(s) backing a Connection. These Connection | selected Protocol Stack(s) backing a Connection. These Connection | |||
Properties may be Generic, applying regardless of transport protocol, | Properties may be Generic, applying regardless of transport protocol, | |||
or Specific, applicable to a single implementation of a single | or Specific, applicable to a single implementation of a single | |||
transport protocol stack. Generic Connection Properties are defined | transport protocol stack. Generic Connection Properties are defined | |||
in Section 7.1 below. Specific Protocol Properties are defined in a | in Section 7.1 below. Specific Protocol Properties are defined in a | |||
transport- and implementation-specific way, and must not be assumed | transport- and implementation-specific way, and MUST NOT be assumed | |||
to apply across different protocols. Attempts to set Specific | to apply across different protocols. Attempts to set Specific | |||
Protocol Properties on a protocol stack not containing that specific | Protocol Properties on a protocol stack not containing that specific | |||
protocol are simply ignored, and do not raise an error; however, too | protocol are simply ignored, and do not raise an error; however, too | |||
much reliance by an application on Specific Protocol Properties may | much reliance by an application on Specific Protocol Properties can | |||
significantly reduce the flexibility of a transport services | significantly reduce the flexibility of a transport services | |||
implementation. | implementation. | |||
The application can set and query Connection Properties on a per- | The application can set and query Connection Properties on a per- | |||
Connection basis. Connection Properties that are not read-only can | Connection basis. Connection Properties that are not read-only can | |||
be set during pre-establishment (see Section 5.2), as well as on | be set during pre-establishment (see Section 5.2), as well as on | |||
connections directly using the SetProperty action: | connections directly using the SetProperty action: | |||
Connection.SetProperty(property, value) | Connection.SetProperty(property, value) | |||
Note that changing one of the Connection Properties on one Connection | Note that changing one of the Connection Properties on one Connection | |||
in a Connection Group will also change it for all other Connections | in a Connection Group will also change it for all other Connections | |||
of that group; see further Section 6.4. | of that group; see further Section 6.4. | |||
At any point, the application can query Connection Properties. | At any point, the application can query Connection Properties. | |||
ConnectionProperties := Connection.GetProperties() | ConnectionProperties := Connection.GetProperties() | |||
Depending on the status of the connection, the queried Connection | Depending on the status of the connection, the queried Connection | |||
Properties will include different information: | Properties will include different information: | |||
skipping to change at page 36, line 5 ¶ | skipping to change at page 39, line 15 ¶ | |||
in a Connection Group will also change it for all other Connections | in a Connection Group will also change it for all other Connections | |||
of that group; see further Section 6.4. | of that group; see further Section 6.4. | |||
At any point, the application can query Connection Properties. | At any point, the application can query Connection Properties. | |||
ConnectionProperties := Connection.GetProperties() | ConnectionProperties := Connection.GetProperties() | |||
Depending on the status of the connection, the queried Connection | Depending on the status of the connection, the queried Connection | |||
Properties will include different information: | Properties will include different information: | |||
o The connection state, which can be one of the following: | * The connection state, which can be one of the following: | |||
Establishing, Established, Closing, or Closed. | Establishing, Established, Closing, or Closed. | |||
o Whether the connection can be used to send data. A connection can | * Whether the connection can be used to send data. A connection can | |||
not be used for sending if the connection was created with the | not be used for sending if the connection was created with the | |||
Selection Property "Direction of Communication" set to | Selection Property "Direction of Communication" set to | |||
"unidirectional receive" or if a Message marked as "Final" was | "unidirectional receive" or if a Message marked as "Final" was | |||
sent over this connection, see Section 8.1.3.5. | sent over this connection, see Section 8.1.3.5. | |||
o Whether the connection can be used to receive data. A connection | * Whether the connection can be used to receive data. A connection | |||
can not be used for reading if the connection was created with the | cannot be used for reading if the connection was created with the | |||
Selection Property "Direction of Communication" set to | Selection Property "Direction of Communication" set to | |||
"unidirectional send" or if a Message marked as "Final" was | "unidirectional send" or if a Message marked as "Final" was | |||
received, see Section 8.3.3.3. The latter is only supported by | received, see Section 8.3.3.3. The latter is only supported by | |||
certain transport protocols, e.g., by TCP as half-closed | certain transport protocols, e.g., by TCP as half-closed | |||
connection. | connection. | |||
o For Connections that are Establishing: Transport Properties that | * For Connections that are Establishing: Transport Properties that | |||
the application specified on the Preconnection, see Section 5.2. | the application specified on the Preconnection, see Section 5.2. | |||
o For Connections that are Established, Closing, or Closed: | * For Connections that are Established, Closing, or Closed: | |||
Selection (Section 5.2) and Connection Properties (Section 7.1) of | Selection (Section 5.2) and Connection Properties (Section 7.1) of | |||
the actual protocols that were selected and instantiated. | the actual protocols that were selected and instantiated. | |||
Selection Properties indicate whether or not the Connection has or | Selection Properties indicate whether or not the Connection has or | |||
offers a certain Selection Property. Note that the actually | offers a certain Selection Property. The actually instantiated | |||
instantiated protocol stack may not match all Protocol Selection | protocol stack might not match all Protocol Selection Properties | |||
Properties that the application specified on the Preconnection. | that the application specified on the Preconnection. For example, | |||
For example, a certain Protocol Selection Property that an | a certain Protocol Selection Property that an application | |||
application specified as Preferred may not actually be present in | specified as Preferred might not actually be present in the chosen | |||
the chosen protocol stack because none of the currently available | protocol stack because none of the currently available transport | |||
transport protocols had this feature. | protocols had this feature. | |||
o For Connections that are Established, additional properties of the | * For Connections that are Established, additional properties of the | |||
path(s) in use. These properties can be derived from the local | path(s) in use. These properties can be derived from the local | |||
provisioning domain [RFC7556], measurements by the Protocol Stack, | provisioning domain [RFC7556], measurements by the Protocol Stack, | |||
or other sources. | or other sources. | |||
7.1. Generic Connection Properties | 7.1. Generic Connection Properties | |||
Generic Connection Properties are defined independent of the chosen | Generic Connection Properties are defined independent of the chosen | |||
protocol stack and therefore available on all Connections. | protocol stack and therefore available on all Connections. | |||
Note that many Connection Properties have a corresponding Selection | Many Connection Properties have a corresponding Selection Property | |||
Property which enables applications to express their preference for | that enables applications to express their preference for protocols | |||
protocols providing a supporting transport feature. | providing a supporting transport feature. | |||
7.1.1. Retransmission Threshold Before Excessive Retransmission | ||||
Notification | ||||
Name: retransmitNotifyThreshold | ||||
Type: Integer, with special value "Disabled" | ||||
Default: Disabled | ||||
This property specifies after how many retransmissions to inform the | ||||
application about "Excessive Retransmissions". | ||||
7.1.2. Required Minimum Corruption Protection Coverage for Receiving | 7.1.1. Required Minimum Corruption Protection Coverage for Receiving | |||
Name: recvChecksumLen | Name: recvChecksumLen | |||
Type: Integer, with special value "Full Coverage" | Type: Integer, with special value "Full Coverage" | |||
Default: Full Coverage | Default: Full Coverage | |||
This property specifies the part of the received data that needs to | This property specifies the minimum number of bytes in a received | |||
be covered by a checksum. It is given in Bytes. A value of 0 means | message that need to be covered by a checksum. A special value of 0 | |||
that no checksum is required. | means that no checksum is permitted. A receiving Endpoint will not | |||
forward messages to the application that have less coverage. The | ||||
application is responsible for handling any corruption within the | ||||
non-protected part of the message [RFC8085]. | ||||
7.1.3. Priority (Connection) | 7.1.2. Connection Priority | |||
Name: connPrio | Name: connPrio | |||
Type: Integer | Type: Integer | |||
Default: 100 | Default: 100 | |||
This Property is a non-negative integer representing the relative | This Property is a non-negative integer representing the relative | |||
inverse priority (i.e., a lower value reflects a higher priority) of | inverse priority (i.e., a lower value reflects a higher priority) of | |||
this Connection relative to other Connections in the same Connection | this Connection relative to other Connections in the same Connection | |||
Group. It has no effect on Connections not part of a Connection | Group. It has no effect on Connections not part of a Connection | |||
Group. As noted in Section 6.4, this property is not entangled when | Group. As noted in Section 6.4, this property is not entangled when | |||
Connections are cloned, i.e., changing the Priority on one Connection | Connections are cloned, i.e., changing the Priority on one Connection | |||
in a Connection Group does not change it on the other Connections in | in a Connection Group does not change it on the other Connections in | |||
the same Connection Group. | the same Connection Group. No guarantees of a specific behavior | |||
regarding Connection Priority are given; a transport system may | ||||
ignore this property. See Section 8.2.6 for more details. | ||||
7.1.4. Timeout for Aborting Connection | 7.1.3. Timeout for Aborting Connection | |||
Name: connTimeout | Name: connTimeout | |||
Type: Numeric, with special value "Disabled" | Type: Numeric, with special value "Disabled" | |||
Default: Disabled | Default: Disabled | |||
This property specifies how long to wait before deciding that a | ||||
Connection has failed when trying to reliably deliver data to the | This property specifies how long to wait before deciding that an | |||
destination. Adjusting this Property will only take effect when the | active Connection has failed when trying to reliably deliver data to | |||
underlying stack supports reliability. The special value "Disabled" | the Remote Endpoint. Adjusting this Property will only take effect | |||
means that this timeout is not scheduled to happen. This can be a | when the underlying stack supports reliability. The special value | |||
valid choice with unreliable data transfer (e.g., when UDP is the | "Disabled" means that this timeout is not scheduled to happen. | |||
underlying transport protocol). | ||||
7.1.4. Timeout for keep alive packets | ||||
Name: keepaliveTimeout | ||||
Type: Numeric, with special value "Default" | ||||
Default: Default | ||||
A transport system can request a protocol that supports sending keep | ||||
alive packets Section 5.2.10. This property specifies the maximum | ||||
time an idle connection (one for which no transport packets have been | ||||
sent) should wait before the Local Endpoint sends a keep-alive packet | ||||
to the Remote Endpoint. Adjusting this Property will only take | ||||
effect when the underlying stack supports sending keep-alive packets. | ||||
Guidance on setting this value for datagram transports is provided in | ||||
[RFC8085]. The special value "Default" means that this timeout will | ||||
use the default for the selected transport. A value greater than the | ||||
connection timeout (Section 7.1.3) will disable the sending of keep- | ||||
alive packets. | ||||
7.1.5. Connection Group Transmission Scheduler | 7.1.5. Connection Group Transmission Scheduler | |||
Name: connScheduler | Name: connScheduler | |||
Type: Enumeration | Type: Enumeration | |||
Default: Weighted Fair Queueing (see Section 3.6 in [RFC8260]) | Default: Weighted Fair Queueing (see Section 3.6 in [RFC8260]) | |||
This property specifies which scheduler should be used among | This property specifies which scheduler should be used among | |||
skipping to change at page 38, line 36 ¶ | skipping to change at page 42, line 8 ¶ | |||
Name: connCapacityProfile | Name: connCapacityProfile | |||
This property specifies the desired network treatment for traffic | This property specifies the desired network treatment for traffic | |||
sent by the application and the tradeoffs the application is prepared | sent by the application and the tradeoffs the application is prepared | |||
to make in path and protocol selection to receive that desired | to make in path and protocol selection to receive that desired | |||
treatment. When the capacity profile is set to a value other than | treatment. When the capacity profile is set to a value other than | |||
Default, the transport system SHOULD select paths and configure | Default, the transport system SHOULD select paths and configure | |||
protocols to optimize the tradeoff between delay, delay variation, | protocols to optimize the tradeoff between delay, delay variation, | |||
and efficient use of the available capacity based on the capacity | and efficient use of the available capacity based on the capacity | |||
profile specified. How this is realized is implementation-specific. | profile specified. How this is realized is implementation-specific. | |||
The Capacity Profile MAY also be used to set priorities on the wire | The Capacity Profile MAY also be used to set markings on the wire for | |||
for Protocol Stacks supporting prioritization. Recommendations for | Protocol Stacks supporting this. Recommendations for use with DSCP | |||
use with DSCP are provided below for each profile; note that when a | are provided below for each profile; note that when a Connection is | |||
Connection is multiplexed, the guidelines in Section 6 of [RFC7657] | multiplexed, the guidelines in Section 6 of [RFC7657] apply. | |||
apply. | ||||
The following values are valid for the Capacity Profile: | The following values are valid for the Capacity Profile: | |||
Default: The application provides no information about its expected | Default: The application provides no information about its expected | |||
capacity profile. Transport system implementations that map the | capacity profile. Transport system implementations that map the | |||
requested capacity profile onto per-connection DSCP signaling | requested capacity profile onto per-connection DSCP signaling | |||
SHOULD assign the DSCP Default Forwarding [RFC2474] PHB. | SHOULD assign the DSCP Default Forwarding [RFC2474] Per Hop | |||
Behaviour (PHB). | ||||
Scavenger: The application is not interactive. It expects to send | Scavenger: The application is not interactive. It expects to send | |||
and/or receive data without any urgency. This can, for example, | and/or receive data without any urgency. This can, for example, | |||
be used to select protocol stacks with scavenger transmission | be used to select protocol stacks with scavenger transmission | |||
control and/or to assign the traffic to a lower-effort service. | control and/or to assign the traffic to a lower-effort service. | |||
Transport system implementations that map the requested capacity | Transport system implementations that map the requested capacity | |||
profile onto per-connection DSCP signaling SHOULD assign the DSCP | profile onto per-connection DSCP signaling SHOULD assign the DSCP | |||
Less than Best Effort [RFC8622] PHB. | Less than Best Effort [RFC8622] PHB. | |||
Low Latency/Interactive: The application is interactive, and prefers | Low Latency/Interactive: The application is interactive, and prefers | |||
skipping to change at page 39, line 24 ¶ | skipping to change at page 42, line 44 ¶ | |||
packets (Nagle's algorithm); to prefer immediate acknowledgment | packets (Nagle's algorithm); to prefer immediate acknowledgment | |||
from the peer endpoint when supported by the underlying transport; | from the peer endpoint when supported by the underlying transport; | |||
and so on. Transport system implementations that map the | and so on. Transport system implementations that map the | |||
requested capacity profile onto per-connection DSCP signaling | requested capacity profile onto per-connection DSCP signaling | |||
without multiplexing SHOULD assign a DSCP Assured Forwarding | without multiplexing SHOULD assign a DSCP Assured Forwarding | |||
(AF41,AF42,AF43,AF44) [RFC2597] PHB. Inelastic traffic that is | (AF41,AF42,AF43,AF44) [RFC2597] PHB. Inelastic traffic that is | |||
expected to conform to the configured network service rate could | expected to conform to the configured network service rate could | |||
be mapped to the DSCP Expedited Forwarding [RFC3246] or [RFC5865] | be mapped to the DSCP Expedited Forwarding [RFC3246] or [RFC5865] | |||
PHBs. | PHBs. | |||
Low Latency/Non-Interactive: The application prefers loss to latency | Low Latency/Non-Interactive: The application prefers loss to | |||
but is not interactive. Response time should be optimized at the | latency, but is not interactive. Response time should be | |||
expense of delay variation and efficient use of the available | optimized at the expense of delay variation and efficient use of | |||
capacity when sending on this connection. Transport system | the available capacity when sending on this connection. Transport | |||
implementations that map the requested capacity profile onto per- | system implementations that map the requested capacity profile | |||
connection DSCP signaling without multiplexing SHOULD assign a | onto per-connection DSCP signaling without multiplexing SHOULD | |||
DSCP Assured Forwarding (AF21,AF22,AF23,AF24) [RFC2597] PHB. | assign a DSCP Assured Forwarding (AF21,AF22,AF23,AF24) [RFC2597] | |||
PHB. | ||||
Constant-Rate Streaming: The application expects to send/receive | Constant-Rate Streaming: The application expects to send/receive | |||
data at a constant rate after Connection establishment. Delay and | data at a constant rate after Connection establishment. Delay and | |||
delay variation should be minimized at the expense of efficient | delay variation should be minimized at the expense of efficient | |||
use of the available capacity. This implies that the Connection | use of the available capacity. This implies that the Connection | |||
may fail if the desired rate cannot be maintained across the Path. | might fail if the desired rate cannot be maintained across the | |||
A transport may interpret this capacity profile as preferring a | Path. A transport can interpret this capacity profile as | |||
circuit breaker [RFC8084] to a rate-adaptive congestion | preferring a circuit breaker [RFC8084] to a rate-adaptive | |||
controller. Transport system implementations that map the | congestion controller. Transport system implementations that map | |||
requested capacity profile onto per-connection DSCP signaling | the requested capacity profile onto per-connection DSCP signaling | |||
without multiplexing SHOULD assign a DSCP Assured Forwarding | without multiplexing SHOULD assign a DSCP Assured Forwarding | |||
(AF31,AF32,AF33,AF34) [RFC2597] PHB. | (AF31,AF32,AF33,AF34) [RFC2597] PHB. | |||
Capacity-Seeking: The application expects to send/receive data at | Capacity-Seeking: The application expects to send/receive data at | |||
the maximum rate allowed by its congestion controller over a | the maximum rate allowed by its congestion controller over a | |||
relatively long period of time. Transport system implementations | relatively long period of time. Transport system implementations | |||
that map the requested capacity profile onto per-connection DSCP | that map the requested capacity profile onto per-connection DSCP | |||
signaling without multiplexing SHOULD assign a DSCP Assured | signaling without multiplexing SHOULD assign a DSCP Assured | |||
Forwarding (AF11,AF12,AF13,AF14) [RFC2597] PHB per Section 4.8 of | Forwarding (AF11,AF12,AF13,AF14) [RFC2597] PHB per Section 4.8 of | |||
[RFC4594]. | [RFC4594]. | |||
skipping to change at page 40, line 17 ¶ | skipping to change at page 43, line 37 ¶ | |||
see Section 8.1.3.8. | see Section 8.1.3.8. | |||
7.1.7. Policy for using Multi-Path Transports | 7.1.7. Policy for using Multi-Path Transports | |||
Name: multipath-policy | Name: multipath-policy | |||
Type: Enumeration | Type: Enumeration | |||
Default: Handover | Default: Handover | |||
This property specifies the local policy of transferring data across | This property specifies the local policy for transferring data across | |||
multiple paths between the same end hosts if Parallel Use of Multiple | multiple paths between the same end hosts if Parallel Use of Multiple | |||
Paths not set to Disabled (see Section 5.2.13). Possible values are: | Paths is not set to Disabled (see Section 5.2.14). Possible values | |||
are: | ||||
Handover: The connection should only attempt to migrate between | Handover: The connection ought only to attempt to migrate between | |||
different paths when the original path is lost or becomes | different paths when the original path is lost or becomes | |||
unusable. The actual thresholds to declare a path unusable are | unusable. The thresholds used to declare a path unusable are | |||
implementation specific. | implementation specific. | |||
Interactive: The connection should attempt to minimize the latency | Interactive: The connection ought only to attempt to minimize the | |||
for interactive traffic patterns by transmitting data across | latency for interactive traffic patterns by transmitting data | |||
multiple paths when it is beneficial to do so. The goal of | across multiple paths when this is beneficial. The goal of | |||
minimizing the latency will be balanced against the cost of each | minimizing the latency will be balanced against the cost of each | |||
of these paths, meaning that depending on the cost of the lower- | of these paths. Depending on the cost of the lower-latency path, | |||
latency path, the scheduling might choose to use a higher-latency | the scheduling might choose to use a higher-latency path. Traffic | |||
path. Traffic can be scheduled such that data may be transmitted | can be scheduled such that data may be transmitted on multiple | |||
on multiple paths in parallel to achieve the lowest latency | paths in parallel to achieve a lower latency. The specific | |||
possible. The specific scheduling algorithm is implementation- | scheduling algorithm is implementation-specific. | |||
specific. | ||||
Aggregate: The connection should attempt to use multiple paths in | Aggregate: The connection ought to attempt to use multiple paths in | |||
parallel in order to maximize bandwidth and possibly overcome | parallel to maximize available capacity and possibly overcome the | |||
bandwidth limitations of the individual paths. The actual | capacity limitations of the individual paths. The actual strategy | |||
strategy is implementation specific. | is implementation specific. | |||
Note that this is a local choice - the peer endpoint can choose a | Note that this is a local choice - the Remote Endpoint can choose a | |||
different policy. | different policy. | |||
7.1.8. Bounds on Send or Receive Rate | 7.1.8. Bounds on Send or Receive Rate | |||
Name: maxSendRate / maxRecvRate | Name: minSendRate / minRecvRate / maxSendRate / maxRecvRate | |||
Type: Numeric (with special value "Unlimited") / Numeric (with | Type: Numeric (with special value "Unlimited") / Numeric (with | |||
special value "Unlimited") | special value "Unlimited") / Numeric (with special value | |||
"Unlimited") / Numeric (with special value "Unlimited") | ||||
Default: Unlimited / Unlimited / Unlimited / Unlimited | ||||
Default: Unlimited / Unlimited | ||||
This property specifies an upper-bound rate that a transfer is not | This property specifies an upper-bound rate that a transfer is not | |||
expected to exceed (even if flow control and congestion control allow | expected to exceed (even if flow control and congestion control allow | |||
higher rates), and/or a lower-bound rate below which the application | higher rates), and/or a lower-bound rate below which the application | |||
does not deem a data transfer useful. It is given in bits per | does not deem it will be useful. These are specified in bits per | |||
second. The special value "Unlimited" indicates that no bound is | second. The special value "Unlimited" indicates that no bound is | |||
specified. | specified. | |||
7.1.9. Read-only Connection Properties | 7.1.9. Group Connection Limit | |||
Name: groupConnLimit | ||||
Type: Numeric (with special value "Unlimited") | ||||
Default: Unlimited | ||||
This property controls the number of Connections that can be accepted | ||||
from a peer as new members of the Connection's group. Similar to | ||||
SetNewConnectionLimit(), this limits the number of ConnectionReceived | ||||
Events that will occur, but constrained to the group of the | ||||
Connection associated with this property. For a multi-streaming | ||||
transport, this limits the number of allowed streams. | ||||
7.1.10. Read-only Connection Properties | ||||
The following generic Connection Properties are read-only, i.e. they | The following generic Connection Properties are read-only, i.e. they | |||
cannot be changed by an application. | cannot be changed by an application. | |||
7.1.9.1. Maximum Message Size Concurrent with Connection Establishment | 7.1.10.1. Maximum Message Size Concurrent with Connection Establishment | |||
Name: zeroRttMsgMaxLen | Name: zeroRttMsgMaxLen | |||
Type: Integer | Type: Integer | |||
This property represents the maximum Message size that can be sent | This property represents the maximum Message size that can be sent | |||
before or during Connection establishment, see also Section 8.1.3.4. | before or during Connection establishment, see also Section 8.1.3.4. | |||
It is given in Bytes. | It is given in Bytes. | |||
7.1.9.2. Maximum Message Size Before Fragmentation or Segmentation | 7.1.10.2. Maximum Message Size Before Fragmentation or Segmentation | |||
Name: singularTransmissionMsgMaxLen | Name: singularTransmissionMsgMaxLen | |||
Type: Integer | Type: Integer | |||
This property, if applicable, represents the maximum Message size | This property, if applicable, represents the maximum Message size | |||
that can be sent without incurring network-layer fragmentation or | that can be sent without incurring network-layer fragmentation or | |||
transport layer segmentation at the sender. This property exposes | transport layer segmentation at the sender. It exposes the Maximum | |||
the Maximum Packet Size (MPS) as described in Datagram PLPMTUD | Packet Size (MPS) as described in Datagram PLPMTUD | |||
[I-D.ietf-tsvwg-datagram-plpmtud]. | [I-D.ietf-tsvwg-datagram-plpmtud]. | |||
7.1.9.3. Maximum Message Size on Send | 7.1.10.3. Maximum Message Size on Send | |||
Name: sendMsgMaxLen | Name: sendMsgMaxLen | |||
Type: Integer | Type: Integer | |||
This property represents the maximum Message size that can be sent | This property represents the maximum Message size that an application | |||
using a send operation. | can send. | |||
7.1.9.4. Maximum Message Size on Receive | 7.1.10.4. Maximum Message Size on Receive | |||
Name: recvMsgMaxLen | Name: recvMsgMaxLen | |||
Type: Integer | Type: Integer | |||
This numeric property represents the maximum Message size that can be | ||||
received. | This numeric property represents the maximum Message size that an | |||
application can receive. | ||||
7.2. TCP-specific Properties: User Timeout Option (UTO) | 7.2. TCP-specific Properties: User Timeout Option (UTO) | |||
These properties specify configurations for the User Timeout Option | These properties specify configurations for the User Timeout Option | |||
(UTO), in case TCP becomes the chosen transport protocol. | (UTO), in the case that TCP becomes the chosen transport protocol. | |||
Implementation is optional and of course only sensible if TCP is | Implementation is optional and useful only if TCP is implemented in | |||
implemented in the transport system. | the transport system. | |||
These TCP-specific properties are included here because the feature | These TCP-specific properties are included here because the feature | |||
"Suggest timeout to the peer" is part of the minimal set of transport | "Suggest timeout to the peer" is part of the minimal set of transport | |||
services [I-D.ietf-taps-minset], where this feature was categorized | services [RFC8923], where this feature was categorized as | |||
as "functional". This means that when an implementation offers this | "functional". This means that when an implementation offers this | |||
feature, it has to expose an interface to it to the application. | feature, it has to expose an interface to it to the application. | |||
Otherwise, the implementation might violate assumptions by the | Otherwise, the implementation might violate assumptions by the | |||
application, which could cause the application to fail. | application, which could cause the application to fail. | |||
All of the below properties are optional (e.g., it is possible to | All of the below properties are optional (e.g., it is possible to | |||
specify "User Timeout Enabled" as true, but not specify an Advertised | specify "User Timeout Enabled" as true, but not specify an Advertised | |||
User Timeout value; in this case, the TCP default will be used). | User Timeout value; in this case, the TCP default will be used). | |||
These properties reflect the API extension specified in Section 3 of | ||||
[RFC5482]. | ||||
7.2.1. Advertised User Timeout | 7.2.1. Advertised User Timeout | |||
Name: tcp.userTimeoutValue | Name: tcp.userTimeoutValue | |||
Type: Integer | Type: Integer | |||
Default: the TCP default | Default: the TCP default | |||
This time value is advertised via the TCP User Timeout Option (UTO) | This time value is advertised via the TCP User Timeout Option (UTO) | |||
[RFC5482] at the remote endpoint to adapt its own "Timeout for | [RFC5482] at the Remote Endpoint to adapt its own "Timeout for | |||
aborting Connection" (see Section 7.1.4) value accordingly. | aborting Connection" (see Section 7.1.3) value. | |||
7.2.2. User Timeout Enabled | 7.2.2. User Timeout Enabled | |||
Name: tcp.userTimeout | Name: tcp.userTimeout | |||
Type: Boolean | Type: Boolean | |||
Default: false | Default: false | |||
This property controls whether the UTO option is enabled for a | This property controls whether the UTO option is enabled for a | |||
skipping to change at page 43, line 12 ¶ | skipping to change at page 47, line 4 ¶ | |||
This property controls whether the UTO option is enabled for a | This property controls whether the UTO option is enabled for a | |||
connection. This applies to both sending and receiving. | connection. This applies to both sending and receiving. | |||
7.2.3. Timeout Changeable | 7.2.3. Timeout Changeable | |||
Name: tcp.userTimeoutRecv | Name: tcp.userTimeoutRecv | |||
Type: Boolean | Type: Boolean | |||
Default: true | Default: true | |||
This property controls whether the "Timeout for aborting Connection" | This property controls whether the "Timeout for aborting Connection" | |||
(see Section 7.1.4) may be changed based on a UTO option received | (see Section 7.1.3) may be changed based on a UTO option received | |||
from the remote peer. This boolean becomes false when "Timeout for | from the remote peer. This boolean becomes false when "Timeout for | |||
aborting Connection" (see Section 7.1.4) is used. | aborting Connection" (see Section 7.1.3) is used. | |||
7.3. Connection Lifecycle Events | 7.3. Connection Lifecycle Events | |||
During the lifetime of a connection there are events that can occur | During the lifetime of a connection there are events that can occur | |||
when configured. | when configured. | |||
7.3.1. Soft Errors | 7.3.1. Soft Errors | |||
Asynchronous introspection is also possible, via the SoftError Event. | Asynchronous introspection is also possible, via the SoftError Event. | |||
This event informs the application about the receipt and contents of | This event informs the application about the receipt and contents of | |||
an ICMP error message related to the Connection. This will only | an ICMP error message related to the Connection. This will only | |||
happen if the underlying protocol stack supports access to soft | happen if the underlying protocol stack supports access to soft | |||
errors; however, even if the underlying stack supports it, there is | errors; however, even if the underlying stack supports it, there is | |||
no guarantee that a soft error will be signaled. | no guarantee that a soft error will be signaled. | |||
Connection -> SoftError<> | Connection -> SoftError<> | |||
7.3.2. Excessive retransmissions | 7.3.2. Path change | |||
This event notifies the application of excessive retransmissions, | This event notifies the application when at least one of the paths | |||
based on a configured threshold (see Section 7.1.1). This will only | underlying a Connection has changed. Changes occur on a single path | |||
happen if the underlying protocol stack supports reliability and, | when the PMTU changes as well as when multiple paths are used and | |||
with it, such notifications. | paths are added or removed, or a handover has been performed. | |||
Connection -> ExcessiveRetransmission<> | Connection -> PathChange<> | |||
8. Data Transfer | 8. Data Transfer | |||
Data is sent and received as Messages, which allows the application | Data is sent and received as Messages, which allows the application | |||
to communicate the boundaries of the data being transferred. | to communicate the boundaries of the data being transferred. | |||
8.1. Messages and Framers | 8.1. Messages and Framers | |||
Each Message has an optional Message Context, which allows to add | Each Message has an optional Message Context, which allows to add | |||
Message Properties, identify Send Events related to a specific | Message Properties, identify Send Events related to a specific | |||
skipping to change at page 44, line 25 ¶ | skipping to change at page 48, line 22 ¶ | |||
Message Properties can be set and queried using the Message Context: | Message Properties can be set and queried using the Message Context: | |||
MessageContext.add(scope?, parameter, value) | MessageContext.add(scope?, parameter, value) | |||
PropertyValue := MessageContext.get(scope?, property) | PropertyValue := MessageContext.get(scope?, property) | |||
To get or set Message Properties, the optional scope parameter is | To get or set Message Properties, the optional scope parameter is | |||
left empty. To get or set meta-data for a Framer, the application | left empty. To get or set meta-data for a Framer, the application | |||
has to pass a reference to this Framer as the scope parameter. | has to pass a reference to this Framer as the scope parameter. | |||
For MessageContexts returned by send events (see Section 8.2.3) and | For MessageContexts returned by send Events (see Section 8.2.2) and | |||
receive events (see Section 8.3.2), the application can query | receive Events (see Section 8.3.2), the application can query | |||
information about the local and remote endpoint: | information about the local and Remote Endpoint: | |||
RemoteEndpoint := MessageContext.GetRemoteEndpoint() | RemoteEndpoint := MessageContext.GetRemoteEndpoint() | |||
LocalEndpoint := MessageContext.GetLocalEndpoint() | LocalEndpoint := MessageContext.GetLocalEndpoint() | |||
Message Contexts can also be used to send messages in reply to other | ||||
messages, see Section 8.2.2 for details. | ||||
8.1.2. Message Framers | 8.1.2. Message Framers | |||
Although most applications communicate over a network using well- | Although most applications communicate over a network using well- | |||
formed Messages, the boundaries and metadata of the Messages are | formed Messages, the boundaries and metadata of the Messages are | |||
often not directly communicated by the transport protocol itself. | often not directly communicated by the transport protocol itself. | |||
For example, HTTP applications send and receive HTTP messages over a | For example, HTTP applications send and receive HTTP messages over a | |||
byte-stream transport, requiring that the boundaries of HTTP messages | byte-stream transport, requiring that the boundaries of HTTP messages | |||
be parsed out from the stream of bytes. | be parsed from the stream of bytes. | |||
Message Framers allow extending a Connection's Protocol Stack to | Message Framers allow extending a Connection's Protocol Stack to | |||
define how to encapsulate or encode outbound Messages, and how to | define how to encapsulate or encode outbound Messages, and how to | |||
decapsulate or decode inbound data into Messages. Message Framers | decapsulate or decode inbound data into Messages. Message Framers | |||
allow message boundaries to be preserved when using a Connection | allow message boundaries to be preserved when using a Connection | |||
object, even when using byte-stream transports. This facility is | object, even when using byte-stream transports. This is designed | |||
designed based on the fact that many of the current application | based on the fact that many of the current application protocols | |||
protocols evolved over TCP, which does not provide message boundary | evolved over TCP, which does not provide message boundary | |||
preservation, and since many of these protocols require message | preservation, and since many of these protocols require message | |||
boundaries to function, each application layer protocol has defined | boundaries to function, each application layer protocol has defined | |||
its own framing. | its own framing. | |||
To use a Message Framer, the application adds it to its Preconnection | To use a Message Framer, the application adds it to its Preconnection | |||
object. Then, the Message Framer can intercept all calls to Send() | object. Then, the Message Framer can intercept all calls to Send() | |||
or Receive() on a Connection to add Message semantics, in addition to | or Receive() on a Connection to add Message semantics, in addition to | |||
interacting with the setup and teardown of the Connection. A Framer | interacting with the setup and teardown of the Connection. A Framer | |||
can start sending data before the application sends data if the | can start sending data before the application sends data if the | |||
framing protocol requires a prefix or handshake (see [RFC8229] for an | framing protocol requires a prefix or handshake (see [RFC8229] for an | |||
skipping to change at page 45, line 38 ¶ | skipping to change at page 49, line 31 ¶ | |||
+----+----------+---------^----------+-----+ | +----+----------+---------^----------+-----+ | |||
| | | | | | | | | | |||
| +-----------------+ | | | +-----------------+ | | |||
| | Byte-stream | | | | | Byte-stream | | | |||
| +-----------------+ | | | +-----------------+ | | |||
| | | | | | | | | | |||
+----v----------v---------+----------v-----+ | +----v----------v---------+----------v-----+ | |||
| Transport Protocol Stack | | | Transport Protocol Stack | | |||
+------------------------------------------+ | +------------------------------------------+ | |||
Figure 1: Protocol Stack showing a Message Framer | ||||
Note that while Message Framers add the most value when placed above | Note that while Message Framers add the most value when placed above | |||
a protocol that otherwise does not preserve message boundaries, they | a protocol that otherwise does not preserve message boundaries, they | |||
can also be used with datagram- or message-based protocols. In these | can also be used with datagram- or message-based protocols. In these | |||
cases, they add an additional transformation to further encode or | cases, they add an additional transformation to further encode or | |||
encapsulate, and can potentially support packing multiple | encapsulate, and can potentially support packing multiple | |||
application-layer Messages into individual transport datagrams. | application-layer Messages into individual transport datagrams. | |||
The API to implement a Message Framer can vary depending on the | The API to implement a Message Framer can vary depending on the | |||
implementation; guidance on implementing Message Framers can be found | implementation; guidance on implementing Message Framers can be found | |||
in [I-D.ietf-taps-impl]. | in [I-D.ietf-taps-impl]. | |||
8.1.2.1. Adding Message Framers to Connections | 8.1.2.1. Adding Message Framers to Connections | |||
The Message Framer object can be added to one or more Preconnections | The Message Framer object can be added to one or more Preconnections | |||
to run on top of transport protocols. Multiple Framers may be added. | to run on top of transport protocols. Multiple Framers may be added | |||
If multiple Framers are added, the last one added runs first when | to a preconnection; in this case, the Framers operate as a framing | |||
framing outbound messages, and last when parsing inbound data. | stack, i.e. the last one added runs first when framing outbound | |||
messages, and last when parsing inbound data. | ||||
The following example adds a basic HTTP Message Framer to a | The following example adds a basic HTTP Message Framer to a | |||
Preconnection: | Preconnection: | |||
framer := NewHTTPMessageFramer() | framer := NewHTTPMessageFramer() | |||
Preconnection.AddFramer(framer) | Preconnection.AddFramer(framer) | |||
Since Message Framers pass from Preconnection to Listener or | ||||
Connection, addition of Framers must happen before any operation that | ||||
may result in the creation of a Connection. | ||||
8.1.2.2. Framing Meta-Data | 8.1.2.2. Framing Meta-Data | |||
When sending Messages, applications can add specific Message values | When sending Messages, applications can add Framer-specific key/value | |||
to a MessageContext (Section 8.1.1) that is intended for a Framer. | pairs to a MessageContext (Section 8.1.1). This mechanism can be | |||
This can be used, for example, to set the type of a Message for a TLV | used, for example, to set the type of a Message for a TLV format. | |||
format. The namespace of values is custom for each unique Message | The namespace of values is custom for each unique Message Framer. | |||
Framer. | ||||
messageContext := NewMessageContext() | messageContext := NewMessageContext() | |||
messageContext.add(framer, key, value) | messageContext.add(framer, key, value) | |||
Connection.Send(messageData, messageContext) | Connection.Send(messageData, messageContext) | |||
When an application receives a MessageContext in a Receive event, it | When an application receives a MessageContext in a Receive event, it | |||
can also look to see if a value was set by a specific Message Framer. | can also look to see if a value was set by a specific Message Framer. | |||
messageContext.get(framer, key) -> value | messageContext.get(framer, key) -> value | |||
For example, if an HTTP Message Framer is used, the values could | For example, if an HTTP Message Framer is used, the values could | |||
correspond to HTTP headers: | correspond to HTTP headers: | |||
httpFramer := NewHTTPMessageFramer() | httpFramer := NewHTTPMessageFramer() | |||
... | ... | |||
messageContext := NewMessageContext() | messageContext := NewMessageContext() | |||
messageContext.add(httpFramer, "accept", "text/html") | messageContext.add(httpFramer, "accept", "text/html") | |||
8.1.3. Message Properties | 8.1.3. Message Properties | |||
Applications may need to annotate the Messages they send with extra | Applications needing to annotate the Messages they send with extra | |||
information to control how data is scheduled and processed by the | information (for example, to control how data is scheduled and | |||
transport protocols in the Connection. Therefore a message context | processed by the transport protocols supporting the Connection) can | |||
containing these properties can be passed to the Send Action. For | include this information in the Message Context passed to the Send | |||
other uses of the message context, see Section 8.1.1. | Action. For other uses of the message context, see Section 8.1.1. | |||
Note that Message Properties are per-Message, not per-Send if partial | Message Properties are per-Message, not per-Send if partial Messages | |||
Messages are sent (Section 8.2.4). All data blocks associated with a | are sent (Section 8.2.3). All data blocks associated with a single | |||
single Message share properties specified in the Message Contexts. | Message share properties specified in the Message Contexts. For | |||
For example, it would not make sense to have the beginning of a | example, it would not make sense to have the beginning of a Message | |||
Message expire, but allow the end of a Message to still be sent. | expire, but allow the end of a Message to still be sent. | |||
A MessageContext object contains metadata for Messages to be sent or | A MessageContext object contains metadata for the Messages to be sent | |||
received. | or received. | |||
messageData := "hello" | messageData := "hello" | |||
messageContext := NewMessageContext() | messageContext := NewMessageContext() | |||
messageContext.add(parameter, value) | messageContext.add(parameter, value) | |||
Connection.Send(messageData, messageContext) | Connection.Send(messageData, messageContext) | |||
The simpler form of Send, which does not take any messageContext, is | The simpler form of Send, which does not take any messageContext, is | |||
equivalent to passing a default MessageContext without adding any | equivalent to passing a default MessageContext without adding any | |||
Message Properties to it. | Message Properties. | |||
If an application wants to override Message Properties for a specific | If an application wants to override Message Properties for a specific | |||
message, it can acquire an empty MessageContext Object and add all | message, it can acquire an empty MessageContext Object and add all | |||
desired Message Properties to that Object. It can then reuse the | desired Message Properties to that Object. It can then reuse the | |||
same messageContext Object for sending multiple Messages with the | same messageContext Object for sending multiple Messages with the | |||
same properties. | same properties. | |||
Properties may be added to a MessageContext object only before the | Properties can be added to a MessageContext object only before the | |||
context is used for sending. Once a messageContext has been used | context is used for sending. Once a messageContext has been used | |||
with a Send call, modifying any of its properties is invalid. | with a Send call, it is invalid to modify any of its properties. | |||
Message Properties may be inconsistent with the properties of the | The Message Properties could be inconsistent with the properties of | |||
Protocol Stacks underlying the Connection on which a given Message is | the Protocol Stacks underlying the Connection on which a given | |||
sent. For example, a Connection must provide reliability to allow | Message is sent. For example, a Protocol Stack must be able to | |||
setting an infinite value for the lifetime property of a Message. | provide ordering if the msgOrdered property of a Message is enabled. | |||
Sending a Message with Message Properties inconsistent with the | Sending a Message with Message Properties inconsistent with the | |||
Selection Properties of the Connection yields an error. | Selection Properties of the Connection yields an error. | |||
Connection Properties describe the default behavior for all Messages | Connection Properties describe the default behavior for all Messages | |||
on a Connection. If a Message Property contradicts a Connection | on a Connection. If a Message Property contradicts a Connection | |||
Property, and if this per-Message behavior can be supported, it | Property, and if this per-Message behavior can be supported, it | |||
overrides the Connection Property for the specific Message. For | overrides the Connection Property for the specific Message. For | |||
example, if "Reliable Data Transfer (Connection)" is set to "Require" | example, if "Reliable Data Transfer (Connection)" is set to "Require" | |||
and a protocol with configurable per-Message reliability is used, | and a protocol with configurable per-Message reliability is used, | |||
setting "Reliable Data Transfer (Message)" to "false" for a | setting "Reliable Data Transfer (Message)" to "false" for a | |||
particular Message will allow this Message to be unreliably | particular Message will allow this Message to be unreliably | |||
delivered. Note that changing the Reliable Data Transfer property on | delivered. Changing the Reliable Data Transfer property on Messages | |||
Messages is only possible for Connections that were established with | is only possible for Connections that were established enabling the | |||
the Selection Property "Configure Per-Message Reliability" enabled. | Selection Property "Configure Per-Message Reliability". | |||
The following Message Properties are supported: | The following Message Properties are supported: | |||
8.1.3.1. Lifetime | 8.1.3.1. Lifetime | |||
Name: msgLifetime | Name: msgLifetime | |||
Type: Numeric | Type: Numeric | |||
Default: infinite | Default: infinite | |||
Lifetime specifies how long a particular Message can wait to be sent | The Lifetime specifies how long a particular Message can wait to be | |||
to the remote endpoint before it is irrelevant and no longer needs to | sent to the Remote Endpoint before it is irrelevant and no longer | |||
be (re-)transmitted. This is a hint to the transport system - it is | needs to be (re-)transmitted. This is a hint to the transport system | |||
not guaranteed that a Message will not be sent when its Lifetime has | - it is not guaranteed that a Message will not be sent when its | |||
expired. | Lifetime has expired. | |||
Setting a Message's Lifetime to infinite indicates that the | Setting a Message's Lifetime to infinite indicates that the | |||
application does not wish to apply a time constraint on the | application does not wish to apply a time constraint on the | |||
transmission of the Message, but it does not express a need for | transmission of the Message, but it does not express a need for | |||
reliable delivery; reliability is adjustable per Message via the | reliable delivery; reliability is adjustable per Message via the | |||
"Reliable Data Transfer (Message)" property (see Section 8.1.3.7). | "Reliable Data Transfer (Message)" property (see Section 8.1.3.7). | |||
The type and units of Lifetime are implementation-specific. | The type and units of Lifetime are implementation-specific. | |||
8.1.3.2. Priority | 8.1.3.2. Priority | |||
skipping to change at page 48, line 45 ¶ | skipping to change at page 52, line 38 ¶ | |||
the priority of a Message, relative to other Messages sent over the | the priority of a Message, relative to other Messages sent over the | |||
same Connection. | same Connection. | |||
A Message with Priority 0 will yield to a Message with Priority 1, | A Message with Priority 0 will yield to a Message with Priority 1, | |||
which will yield to a Message with Priority 2, and so on. Priorities | which will yield to a Message with Priority 2, and so on. Priorities | |||
may be used as a sender-side scheduling construct only, or be used to | may be used as a sender-side scheduling construct only, or be used to | |||
specify priorities on the wire for Protocol Stacks supporting | specify priorities on the wire for Protocol Stacks supporting | |||
prioritization. | prioritization. | |||
Note that this property is not a per-message override of the | Note that this property is not a per-message override of the | |||
connection Priority - see Section 7.1.3. Both Priority properties | connection Priority - see Section 7.1.2. The Priority properties may | |||
may interact, but can be used independently and be realized by | interact, but can be used independently and be realized by different | |||
different mechanisms. | mechanisms; see Section 8.2.6. | |||
8.1.3.3. Ordered | 8.1.3.3. Ordered | |||
Name: msgOrdered | Name: msgOrdered | |||
Type: Boolean | Type: Boolean | |||
Default: true | Default: the queried Boolean value of the Selection Property | |||
"reliability" (Section 5.2.1) | ||||
If true, it specifies that the receiver-side transport protocol stack | The order in which Messages were submitted for transmission via the | |||
may only deliver the Message to the receiving application after the | Send Action will be preserved on delivery via Receive<> events for | |||
previous ordered Message which was passed to the same Connection via | all Messages on a Connection that have this Message Property set to | |||
the Send Action, when such a Message exists. If false, the Message | true. | |||
may be delivered to the receiving application out of order. This | ||||
property is used for protocols that support preservation of data | If false, the Message is delivered to the receiving application | |||
ordering, see Section 5.2.4, but allow out-of-order delivery for | without preserving the ordering. This property is used for protocols | |||
certain messages, e.g., by multiplexing independent messages onto | that support preservation of data ordering, see Section 5.2.4, but | |||
different streams. | allow out-of-order delivery for certain messages, e.g., by | |||
multiplexing independent messages onto different streams. | ||||
8.1.3.4. Safely Replayable | 8.1.3.4. Safely Replayable | |||
Name: safelyReplayable | Name: safelyReplayable | |||
Type: Boolean | Type: Boolean | |||
Default: false | Default: false | |||
If true, it specifies that a Message is safe to send to the remote | If true, Safely Replayable specifies that a Message is safe to send | |||
endpoint more than once for a single Send Action. It is used to mark | to the Remote Endpoint more than once for a single Send Action. It | |||
data safe for certain 0-RTT establishment techniques, where | marks the data as safe for certain 0-RTT establishment techniques, | |||
retransmission of the 0-RTT data may cause the remote application to | where retransmission of the 0-RTT data may cause the remote | |||
receive the Message multiple times. | application to receive the Message multiple times. | |||
Note that for protocols that do not protect against duplicated | For protocols that do not protect against duplicated messages, e.g., | |||
messages, e.g., UDP, all messages MUST be marked as "Safely | UDP, all messages need to be marked as "Safely Replayable". To | |||
Replayable". In order to enable protocol selection to choose such a | enable protocol selection to choose such a protocol, "Safely | |||
protocol, "Safely Replayable" MUST be added to the | Replayable" needs to be added to the TransportProperties passed to | |||
TransportProperties passed to the Preconnection. If such a protocol | the Preconnection. If such a protocol was chosen, disabling "Safely | |||
was chosen, disabling "Safely Replayable" on individual messages MUST | Replayable" on individual messages MUST result in a SendError. | |||
result in a SendError. | ||||
8.1.3.5. Final | 8.1.3.5. Final | |||
Name: final | Name: final | |||
Type: Boolean | Type: Boolean | |||
Default: false | Default: false | |||
If true, this Message is the last one that the application will send | ||||
on a Connection. This allows underlying protocols to indicate to the | ||||
Remote Endpoint that the Connection has been effectively closed in | ||||
the sending direction. For example, TCP-based Connections can send a | ||||
FIN once a Message marked as Final has been completely sent, | ||||
indicated by marking endOfMessage. Protocols that do not support | ||||
signalling the end of a Connection in a given direction will ignore | ||||
this property. | ||||
Note that a Final Message must always be sorted to the end of a list | If true, this indicates a Message is the last that the application | |||
of Messages. The Final property overrides Priority and any other | will send on a Connection. This allows underlying protocols to | |||
indicate to the Remote Endpoint that the Connection has been | ||||
effectively closed in the sending direction. For example, TCP-based | ||||
Connections can send a FIN once a Message marked as Final has been | ||||
completely sent, indicated by marking endOfMessage. Protocols that | ||||
do not support signalling the end of a Connection in a given | ||||
direction will ignore this property. | ||||
A Final Message must always be sorted to the end of a list of | ||||
Messages. The Final property overrides Priority and any other | ||||
property that would re-order Messages. If another Message is sent | property that would re-order Messages. If another Message is sent | |||
after a Message marked as Final has already been sent on a | after a Message marked as Final has already been sent on a | |||
Connection, the Send Action for the new Message will cause a | Connection, the Send Action for the new Message will cause a | |||
SendError Event. | SendError Event. | |||
8.1.3.6. Corruption Protection Length | 8.1.3.6. Sending Corruption Protection Length | |||
Name: msgChecksumLen | Name: msgChecksumLen | |||
Type: Integer (non-negative with special value "Full Coverage") | Type: Integer (non-negative with special value "Full Coverage") | |||
Default: Full Coverage | Default: Full Coverage | |||
This property specifies the minimum length of the section of the | This property specifies the minimum length of the section of a sent | |||
Message, starting from byte 0, that the application requires to be | Message, starting from byte 0, that the application requires to be | |||
delivered without corruption due to lower layer errors. It is used | delivered without corruption due to lower layer errors. It is used | |||
to specify options for simple integrity protection via checksums. A | to specify options for simple integrity protection via checksums. A | |||
value of 0 means that no checksum is required, and "Full Coverage" | value of 0 means that no checksum is required, and "Full Coverage" | |||
means that the entire Message is protected by a checksum. Only "Full | means that the entire Message needs to be protected by a checksum. | |||
Coverage" is guaranteed, any other requests are advisory, meaning | Only "Full Coverage" is guaranteed, any other requests are advisory, | |||
that "Full Coverage" is applied anyway. | which may result in "Full Coverage" being applied. | |||
8.1.3.7. Reliable Data Transfer (Message) | 8.1.3.7. Reliable Data Transfer (Message) | |||
Name: msgReliable | Name: msgReliable | |||
Type: Boolean | Type: Boolean | |||
Default: true | Default: the queried Boolean value of the Selection Property | |||
"reliability" (Section 5.2.1) | ||||
When true, this property specifies that a message should be sent in | When true, this property specifies that a Message should be sent in | |||
such a way that the transport protocol ensures all data is received | such a way that the transport protocol ensures all data is received | |||
on the other side without corruption. Changing the "Reliable Data | on the other side without corruption. Changing the "Reliable Data | |||
Transfer" property on Messages is only possible for Connections that | Transfer" property on Messages is only possible for Connections that | |||
were established with the Selection Property "Configure Per-Message | were established enabling the Selection Property "Configure Per- | |||
Reliability" enabled. When this is not the case, changing it will | Message Reliability". When this is not the case, changing | |||
generate an error. Disabling this property indicates that the | "msgReliable" will generate an error. | |||
transport system may disable retransmissions or other reliability | ||||
mechanisms for this particular Message, but such disabling is not | Disabling this property indicates that the transport system may | |||
guaranteed. | disable retransmissions or other reliability mechanisms for this | |||
particular Message, but such disabling is not guaranteed. | ||||
8.1.3.8. Message Capacity Profile Override | 8.1.3.8. Message Capacity Profile Override | |||
Name: msgCapacityProfile | Name: msgCapacityProfile | |||
Type: Enumeration | Type: Enumeration | |||
Default: inherited from the Connection Property | ||||
"connCapacityProfile" (Section 7.1.6) | ||||
This enumerated property specifies the application's preferred | This enumerated property specifies the application's preferred | |||
tradeoffs for sending this Message; it is a per-Message override of | tradeoffs for sending this Message; it is a per-Message override of | |||
the Capacity Profile connection property (see Section 7.1.6). | the Capacity Profile connection property (see Section 7.1.6). | |||
8.1.3.9. No Fragmentation | 8.1.3.9. No Network-Layer Fragmentation | |||
Name: noFragmentation | Name: noFragmentation | |||
Type: Boolean | Type: Boolean | |||
Default: false | Default: false | |||
This property specifies that a message should be sent and received as | This property specifies that a message should be sent and received as | |||
a single packet without network-layer fragmentation, if possible. | a single packet without network-layer fragmentation, if possible. | |||
Attempts to send a message with this property set with a size greater | This only takes effect when the transport uses a network layer that | |||
to the transport's current estimate of its maximum transmission | supports this functionality. When it does take effect, setting this | |||
segment size will result in a "SendError". When used with transports | property to true will cause the Don't Fragment bit to be set in the | |||
supporting this functionality and running over IP version 4, the | IP header, and attempts to send a message with this property set to a | |||
Don't Fragment bit will be set. | size greater than the transport's current estimate of its maximum | |||
packet size ("singularTransmissionMsgMaxLen") will result in a | ||||
"SendError". | ||||
8.1.3.10. No Segmentation | ||||
Name: noTransportFragmentation | ||||
Type: Boolean | ||||
Default: false | ||||
When set to true, this property requests the network layer at the | ||||
sending endpoint to not fragment the packets generated by the | ||||
transport layer. When running over IPv4, setting this property to | ||||
true will also cause the Don't Fragment bit to be set in the IP | ||||
header. When this property is set, an attempt to send a message size | ||||
greater than the transport's current estimate of its maximum packet | ||||
size (singularTransmissionMsgMaxLen) will result in a SendError. | ||||
This only takes effect when the transport and network layer support | ||||
this functionality. | ||||
8.2. Sending Data | 8.2. Sending Data | |||
Once a Connection has been established, it can be used for sending | Once a Connection has been established, it can be used for sending | |||
Messages. By default, Send enqueues a complete Message, and takes | Messages. By default, Send enqueues a complete Message, and takes | |||
optional per-Message properties (see Section 8.2.1). All Send | optional per-Message properties (see Section 8.2.1). All Send | |||
actions are asynchronous, and deliver events (see Section 8.2.3). | actions are asynchronous, and deliver Events (see Section 8.2.2). | |||
Sending partial Messages for streaming large data is also supported | Sending partial Messages for streaming large data is also supported | |||
(see Section 8.2.4). | (see Section 8.2.3). | |||
Messages are sent on a Connection using the Send action: | Messages are sent on a Connection using the Send action: | |||
Connection.Send(messageData, messageContext?, endOfMessage?) | Connection.Send(messageData, messageContext?, endOfMessage?) | |||
where messageData is the data object to send, and messageContext | where messageData is the data object to send, and messageContext | |||
allows adding Message Properties, identifying Send Events related to | allows adding Message Properties, identifying Send Events related to | |||
a specific Message or inspecting meta-data related to the Message | a specific Message or inspecting meta-data related to the Message | |||
sent (see Section 8.1.1). | sent (see Section 8.1.1). | |||
The optional endOfMessage parameter supports partial sending and is | The optional endOfMessage parameter supports partial sending and is | |||
described in Section 8.2.4. | described in Section 8.2.3. | |||
8.2.1. Basic Sending | 8.2.1. Basic Sending | |||
The most basic form of sending on a connection involves enqueuing a | The most basic form of sending on a connection involves enqueuing a | |||
single Data block as a complete Message, with default Message | single Data block as a complete Message with default Message | |||
Properties. | Properties. | |||
messageData := "hello" | messageData := "hello" | |||
Connection.Send(messageData) | Connection.Send(messageData) | |||
The interpretation of a Message to be sent is dependent on the | The interpretation of a Message to be sent is dependent on the | |||
implementation, and on the constraints on the Protocol Stacks implied | implementation, and on the constraints on the Protocol Stacks implied | |||
by the Connection's transport properties. For example, a Message may | by the Connection's transport properties. For example, a Message may | |||
be a single datagram for UDP Connections; or an HTTP Request for HTTP | be a single datagram for UDP Connections; or an HTTP Request for HTTP | |||
Connections. | Connections. | |||
Some transport protocols can deliver arbitrarily sized Messages, but | Some transport protocols can deliver arbitrarily sized Messages, but | |||
other protocols constrain the maximum Message size. Applications can | other protocols constrain the maximum Message size. Applications can | |||
query the Connection Property "Maximum Message size on send" | query the Connection Property "Maximum Message size on send" | |||
(Section 7.1.9.3) to determine the maximum size allowed for a single | (Section 7.1.10.3) to determine the maximum size allowed for a single | |||
Message. If a Message is too large to fit in the Maximum Message | Message. If a Message is too large to fit in the Maximum Message | |||
Size for the Connection, the Send will fail with a SendError event | Size for the Connection, the Send will fail with a SendError event | |||
(Section 8.2.3.3). For example, it is invalid to send a Message over | (Section 8.2.2.3). For example, it is invalid to send a Message over | |||
a UDP connection that is larger than the available datagram sending | a UDP connection that is larger than the available datagram sending | |||
size. | size. | |||
8.2.2. Sending Replies | 8.2.2. Send Events | |||
When a message is sent in response to a message received, the | ||||
application may use the Message Context of the received Message to | ||||
construct a Message Context for the reply. | ||||
replyMessageContext := requestMessageContext.reply() | ||||
By using the "replyMessageContext", the transport system is informed | ||||
that the message to be sent is a response and can map the response to | ||||
the same underlying transport connection or stream the request was | ||||
received from. The concept of Message Contexts is described in | ||||
Section 8.1.1. | ||||
8.2.3. Send Events | ||||
Like all Actions in this interface, the Send Action is asynchronous. | Like all Actions in this interface, the Send Action is asynchronous. | |||
There are several Events that can be delivered in response to Sending | There are several Events that can be delivered in response to Sending | |||
a Message. Exactly one Event (Sent, Expired, or SendError) will be | a Message. Exactly one Event (Sent, Expired, or SendError) will be | |||
delivered in response to each call to Send. | delivered in response to each call to Send. | |||
Note that if partial Sends are used (Section 8.2.4), there will still | Note that if partial Sends are used (Section 8.2.3), there will still | |||
be exactly one Send Event delivered for each call to Send. For | be exactly one Send Event delivered for each call to Send. For | |||
example, if a Message expired while two requests to Send data for | example, if a Message expired while two requests to Send data for | |||
that Message are outstanding, there will be two Expired events | that Message are outstanding, there will be two Expired events | |||
delivered. | delivered. | |||
The interface should allow the application to correlate which Send | The interface should allow the application to correlate which Send | |||
Action resulted in a particular Send Event. The manner in which this | Action resulted in a particular Send Event. The manner in which this | |||
correlation is indicated is implementation-specific. | correlation is indicated is implementation-specific. | |||
8.2.3.1. Sent | 8.2.2.1. Sent | |||
Connection -> Sent<messageContext> | Connection -> Sent<messageContext> | |||
The Sent Event occurs when a previous Send Action has completed, | The Sent Event occurs when a previous Send Action has completed, | |||
i.e., when the data derived from the Message has been passed down or | i.e., when the data derived from the Message has been passed down or | |||
through the underlying Protocol Stack and is no longer the | through the underlying Protocol Stack and is no longer the | |||
responsibility of this interface. The exact disposition of the | responsibility of this interface. The exact disposition of the | |||
Message (i.e., whether it has actually been transmitted, moved into a | Message (i.e., whether it has actually been transmitted, moved into a | |||
buffer on the network interface, moved into a kernel buffer, and so | buffer on the network interface, moved into a kernel buffer, and so | |||
on) when the Sent Event occurs is implementation-specific. The Sent | on) when the Sent Event occurs is implementation-specific. The Sent | |||
Event contains a reference to the Message to which it applies. | Event contains a reference to the Message to which it applies. | |||
Sent Events allow an application to obtain an understanding of the | Sent Events allow an application to obtain an understanding of the | |||
amount of buffering it creates. That is, if an application calls the | amount of buffering it creates. That is, if an application calls the | |||
Send Action multiple times without waiting for a Sent Event, it has | Send Action multiple times without waiting for a Sent Event, it has | |||
created more buffer inside the transport system than an application | created more buffer inside the transport system than an application | |||
that always waits for the Sent Event before calling the next Send | that always waits for the Sent Event before calling the next Send | |||
Action. | Action. | |||
8.2.3.2. Expired | 8.2.2.2. Expired | |||
Connection -> Expired<messageContext> | Connection -> Expired<messageContext> | |||
The Expired Event occurs when a previous Send Action expired before | The Expired Event occurs when a previous Send Action expired before | |||
completion; i.e. when the Message was not sent before its Lifetime | completion; i.e. when the Message was not sent before its Lifetime | |||
(see Section 8.1.3.1) expired. This is separate from SendError, as | (see Section 8.1.3.1) expired. This is separate from SendError, as | |||
it is an expected behavior for partially reliable transports. The | it is an expected behavior for partially reliable transports. The | |||
Expired Event contains a reference to the Message to which it | Expired Event contains a reference to the Message to which it | |||
applies. | applies. | |||
8.2.3.3. SendError | 8.2.2.3. SendError | |||
Connection -> SendError<messageContext, reason?> | Connection -> SendError<messageContext, reason?> | |||
A SendError occurs when a Message could not be sent due to an error | A SendError occurs when a Message was not sent due to an error | |||
condition: an attempt to send a Message which is too large for the | condition: an attempt to send a Message which is too large for the | |||
system and Protocol Stack to handle, some failure of the underlying | system and Protocol Stack to handle, some failure of the underlying | |||
Protocol Stack, or a set of Message Properties not consistent with | Protocol Stack, or a set of Message Properties not consistent with | |||
the Connection's transport properties. The SendError contains a | the Connection's transport properties. The SendError contains a | |||
reference to the Message to which it applies. | reference to the Message to which it applies. | |||
8.2.4. Partial Sends | 8.2.3. Partial Sends | |||
It is not always possible for an application to send all data | It is not always possible for an application to send all data | |||
associated with a Message in a single Send Action. The Message data | associated with a Message in a single Send Action. The Message data | |||
may be too large for the application to hold in memory at one time, | may be too large for the application to hold in memory at one time, | |||
or the length of the Message may be unknown or unbounded. | or the length of the Message may be unknown or unbounded. | |||
Partial Message sending is supported by passing an endOfMessage | Partial Message sending is supported by passing an endOfMessage | |||
boolean parameter to the Send Action. This value is always true by | boolean parameter to the Send Action. This value is always true by | |||
default, and the simpler forms of Send are equivalent to passing true | default, and the simpler forms of Send are equivalent to passing true | |||
for endOfMessage. | for endOfMessage. | |||
skipping to change at page 54, line 37 ¶ | skipping to change at page 58, line 45 ¶ | |||
Connection.Send(messageData, messageContext, endOfMessage) | Connection.Send(messageData, messageContext, endOfMessage) | |||
messageData := "lo" | messageData := "lo" | |||
endOfMessage := true | endOfMessage := true | |||
Connection.Send(messageData, messageContext, endOfMessage) | Connection.Send(messageData, messageContext, endOfMessage) | |||
All data sent with the same MessageContext object will be treated as | All data sent with the same MessageContext object will be treated as | |||
belonging to the same Message, and will constitute an in-order series | belonging to the same Message, and will constitute an in-order series | |||
until the endOfMessage is marked. | until the endOfMessage is marked. | |||
8.2.5. Batching Sends | 8.2.4. Batching Sends | |||
To reduce the overhead of sending multiple small Messages on a | To reduce the overhead of sending multiple small Messages on a | |||
Connection, the application may want to batch several Send Actions | Connection, the application could batch several Send Actions | |||
together. This provides a hint to the system that the sending of | together. This provides a hint to the system that the sending of | |||
these Messages should be coalesced when possible, and that sending | these Messages ought to be coalesced when possible, and that sending | |||
any of the batched Messages may be delayed until the last Message in | any of the batched Messages can be delayed until the last Message in | |||
the batch is enqueued. | the batch is enqueued. | |||
The semantics for starting and ending a batch can be implementation- | The semantics for starting and ending a batch can be implementation- | |||
specific, but need to allow multiple Send Actions to be enqueued. | specific, but need to allow multiple Send Actions to be enqueued. | |||
Connection.StartBatch() | Connection.StartBatch() | |||
Connection.Send(messageData) | Connection.Send(messageData) | |||
Connection.Send(messageData) | Connection.Send(messageData) | |||
Connection.EndBatch() | Connection.EndBatch() | |||
8.2.6. Send on Active Open: InitiateWithSend | 8.2.5. Send on Active Open: InitiateWithSend | |||
For application-layer protocols where the Connection initiator also | For application-layer protocols where the Connection initiator also | |||
sends the first message, the InitiateWithSend() action combines | sends the first message, the InitiateWithSend() action combines | |||
Connection initiation with a first Message sent: | Connection initiation with a first Message sent: | |||
Connection := Preconnection.InitiateWithSend(messageData, messageContext?, timeout?) | Connection := Preconnection.InitiateWithSend(messageData, messageContext?, timeout?) | |||
Whenever possible, a messageContext should be provided to declare the | Whenever possible, a messageContext should be provided to declare the | |||
Message passed to InitiateWithSend as "Safely Replayable". This | Message passed to InitiateWithSend as "Safely Replayable". This | |||
allows the transport system to make use of 0-RTT establishment in | allows the transport system to make use of 0-RTT establishment in | |||
skipping to change at page 55, line 36 ¶ | skipping to change at page 59, line 39 ¶ | |||
Neither partial sends nor send batching are supported by | Neither partial sends nor send batching are supported by | |||
InitiateWithSend(). | InitiateWithSend(). | |||
The Events that may be sent after InitiateWithSend() are equivalent | The Events that may be sent after InitiateWithSend() are equivalent | |||
to those that would be sent by an invocation of Initiate() followed | to those that would be sent by an invocation of Initiate() followed | |||
immediately by an invocation of Send(), with the caveat that a send | immediately by an invocation of Send(), with the caveat that a send | |||
failure that occurs because the Connection could not be established | failure that occurs because the Connection could not be established | |||
will not result in a SendError separate from the InitiateError | will not result in a SendError separate from the InitiateError | |||
signaling the failure of Connection establishment. | signaling the failure of Connection establishment. | |||
8.2.6. Priority in TAPS | ||||
The Transport Services interface provides two properties to allow a | ||||
sender to signal the relative priority of data transmission: the | ||||
Priority Message Property Section 8.1.3.2, and the Connection | ||||
Priority Connection Property Section 7.1.2. These properties are | ||||
designed to allow the expression and implementation of a wide variety | ||||
of approaches to transmission priority in the transport and | ||||
application layer, including those which do not appear on the wire | ||||
(affecting only sender-side transmission scheduling) as well as those | ||||
that do (e.g. [I-D.ietf-httpbis-priority]. | ||||
A Transport Services system gives no guarantees about how its | ||||
expression of relative priorities will be realized; for example, if a | ||||
transport stack that only provides a single in-order reliable stream | ||||
is selected, prioritization information can only be ignored. | ||||
However, the Transport Services system will seek to ensure that | ||||
performance of relatively-prioritized connections and messages is not | ||||
worse with respect to those connections and messages than an | ||||
equivalent configuration in which all prioritization properties are | ||||
left at their defaults. | ||||
The Transport Services interface does order Connection Priority over | ||||
the Priority Message Property. In the absense of other externalities | ||||
(e.g., transport-layer flow control), a priority 1 Message on a | ||||
priority 0 Connection will be sent before a priority 0 Message on a | ||||
priority 1 Connection in the same group. | ||||
8.3. Receiving Data | 8.3. Receiving Data | |||
Once a Connection is established, it can be used for receiving data | Once a Connection is established, it can be used for receiving data | |||
(unless the "Direction of Communication" property is set to | (unless the "Direction of Communication" property is set to | |||
"unidirectional send"). As with sending, data is received in terms | "unidirectional send"). As with sending, the data is received in | |||
of Messages. Receiving is an asynchronous operation, in which each | Messages. Receiving is an asynchronous operation, in which each call | |||
call to Receive enqueues a request to receive new data from the | to Receive enqueues a request to receive new data from the | |||
connection. Once data has been received, or an error is encountered, | connection. Once data has been received, or an error is encountered, | |||
an event will be delivered to complete any pending Receive requests | an event will be delivered to complete any pending Receive requests | |||
(see Section 8.3.2). If Messages arrive at the transport system | (see Section 8.3.2). If Messages arrive at the transport system | |||
before Receive requests are issued, ensuing Receive requests will | before Receive requests are issued, ensuing Receive requests will | |||
first operate on these Messages before awaiting any further Messages. | first operate on these Messages before awaiting any further Messages. | |||
8.3.1. Enqueuing Receives | 8.3.1. Enqueuing Receives | |||
Receive takes two parameters to specify the length of data that an | Receive takes two parameters to specify the length of data that an | |||
application is willing to receive, both of which are optional and | application is willing to receive, both of which are optional and | |||
skipping to change at page 56, line 30 ¶ | skipping to change at page 61, line 10 ¶ | |||
Section 8.3.2.2 and Section 8.1.2 for more information on how this is | Section 8.3.2.2 and Section 8.1.2 for more information on how this is | |||
accomplished). If this value is set to some smaller value, the | accomplished). If this value is set to some smaller value, the | |||
associated receive event will be triggered only when at least that | associated receive event will be triggered only when at least that | |||
many bytes are available, or the Message is complete with fewer | many bytes are available, or the Message is complete with fewer | |||
bytes, or the system needs to free up memory. Applications should | bytes, or the system needs to free up memory. Applications should | |||
always check the length of the data delivered to the receive event | always check the length of the data delivered to the receive event | |||
and not assume it will be as long as minIncompleteLength in the case | and not assume it will be as long as minIncompleteLength in the case | |||
of shorter complete Messages or memory issues. | of shorter complete Messages or memory issues. | |||
The maxLength argument indicates the maximum size of a Message in | The maxLength argument indicates the maximum size of a Message in | |||
bytes the application is currently prepared to receive. The default | bytes that the application is currently prepared to receive. The | |||
value for maxLength is infinite. If an incoming Message is larger | default value for maxLength is infinite. If an incoming Message is | |||
than the minimum of this size and the maximum Message size on receive | larger than the minimum of this size and the maximum Message size on | |||
for the Connection's Protocol Stack, it will be delivered via | receive for the Connection's Protocol Stack, it will be delivered via | |||
ReceivedPartial events (Section 8.3.2.2). | ReceivedPartial events (Section 8.3.2.2). | |||
Note that maxLength does not guarantee that the application will | Note that maxLength does not guarantee that the application will | |||
receive that many bytes if they are available; the interface may | receive that many bytes if they are available; the interface could | |||
return ReceivedPartial events with less data than maxLength according | return ReceivedPartial events with less data than maxLength according | |||
to implementation constraints. Note also that maxLength and | to implementation constraints. Note also that maxLength and | |||
minIncompleteLength are intended only to manage buffering, and are | minIncompleteLength are intended only to manage buffering, and are | |||
not interpreted as a receiver preference for message reordering. | not interpreted as a receiver preference for message reordering. | |||
8.3.2. Receive Events | 8.3.2. Receive Events | |||
Each call to Receive will be paired with a single Receive Event, | Each call to Receive will be paired with a single Receive Event, | |||
which can be a success or an error. This allows an application to | which can be a success or an error. This allows an application to | |||
provide backpressure to the transport stack when it is temporarily | provide backpressure to the transport stack when it is temporarily | |||
skipping to change at page 57, line 27 ¶ | skipping to change at page 62, line 10 ¶ | |||
map responses to their requests. See Section 8.1.1 for details. | map responses to their requests. See Section 8.1.1 for details. | |||
See Section 8.1.2 for handling Message framing in situations where | See Section 8.1.2 for handling Message framing in situations where | |||
the Protocol Stack only provides a byte-stream transport. | the Protocol Stack only provides a byte-stream transport. | |||
8.3.2.2. ReceivedPartial | 8.3.2.2. ReceivedPartial | |||
Connection -> ReceivedPartial<messageData, messageContext, endOfMessage> | Connection -> ReceivedPartial<messageData, messageContext, endOfMessage> | |||
If a complete Message cannot be delivered in one event, one part of | If a complete Message cannot be delivered in one event, one part of | |||
the Message may be delivered with a ReceivedPartial event. In order | the Message can be delivered with a ReceivedPartial event. To | |||
to continue to receive more of the same Message, the application must | continue to receive more of the same Message, the application must | |||
invoke Receive again. | invoke Receive again. | |||
Multiple invocations of ReceivedPartial deliver data for the same | Multiple invocations of ReceivedPartial deliver data for the same | |||
Message by passing the same MessageContext, until the endOfMessage | Message by passing the same MessageContext, until the endOfMessage | |||
flag is delivered or a ReceiveError occurs. All partial blocks of a | flag is delivered or a ReceiveError occurs. All partial blocks of a | |||
single Message are delivered in order without gaps. This event does | single Message are delivered in order without gaps. This event does | |||
not support delivering discontiguous partial Messages. | not support delivering discontiguous partial Messages. If, for | |||
example, Message A is divided into three pieces (A1, A2, A3) and | ||||
Message B is divided into three pieces (B1, B2, B3), the | ||||
ReceivedPartial may deliver them in a sequence like this: A1, B1, B2, | ||||
A2, A3, B3, 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 the minIncompleteLength in the Receive request was set to be | If the minIncompleteLength in the Receive request was set to be | |||
infinite (indicating a request to receive only complete Messages), | infinite (indicating a request to receive only complete Messages), | |||
the ReceivedPartial event may still be delivered if one of the | the ReceivedPartial event may still be delivered if one of the | |||
following conditions is true: | following conditions is true: | |||
o the underlying Protocol Stack supports message boundary | * the underlying Protocol Stack supports message boundary | |||
preservation, and the size of the Message is larger than the | preservation, and the size of the Message is larger than the | |||
buffers available for a single message; | buffers available for a single message; | |||
o the underlying Protocol Stack does not support message boundary | * the underlying Protocol Stack does not support message boundary | |||
preservation, and the Message Framer (see Section 8.1.2) cannot | preservation, and the Message Framer (see Section 8.1.2) cannot | |||
determine the end of the message using the buffer space it has | determine the end of the message using the buffer space it has | |||
available; or | available; or | |||
o the underlying Protocol Stack does not support message boundary | * the underlying Protocol Stack does not support message boundary | |||
preservation, and no Message Framer was supplied by the | preservation, and no Message Framer was supplied by the | |||
application | application | |||
Note that in the absence of message boundary preservation or a | Note that in the absence of message boundary preservation or a | |||
Message Framer, all bytes received on the Connection will be | Message Framer, all bytes received on the Connection will be | |||
represented as one large Message of indeterminate length. | represented as one large Message of indeterminate length. | |||
8.3.2.3. ReceiveError | 8.3.2.3. ReceiveError | |||
Connection -> ReceiveError<messageContext, reason?> | Connection -> ReceiveError<messageContext, reason?> | |||
skipping to change at page 58, line 16 ¶ | skipping to change at page 63, line 4 ¶ | |||
preservation, and no Message Framer was supplied by the | preservation, and no Message Framer was supplied by the | |||
application | application | |||
Note that in the absence of message boundary preservation or a | Note that in the absence of message boundary preservation or a | |||
Message Framer, all bytes received on the Connection will be | Message Framer, all bytes received on the Connection will be | |||
represented as one large Message of indeterminate length. | represented as one large Message of indeterminate length. | |||
8.3.2.3. ReceiveError | 8.3.2.3. ReceiveError | |||
Connection -> ReceiveError<messageContext, reason?> | Connection -> ReceiveError<messageContext, reason?> | |||
A ReceiveError occurs when data is received by the underlying | A ReceiveError occurs when data is received by the underlying | |||
Protocol Stack that cannot be fully retrieved or parsed, or when some | Protocol Stack that cannot be fully retrieved or parsed, or when some | |||
other indication is received that reception has failed. In contrast, | other indication is received that reception has failed. In contrast, | |||
conditions that irrevocably lead to the termination of the Connection | conditions that irrevocably lead to the termination of the Connection | |||
are signaled using ConnectionError instead (see Section 9). | are instead signaled using ConnectionError (see Section 9). | |||
The ReceiveError event passes an optional associated MessageContext. | The ReceiveError event passes an optional associated MessageContext. | |||
This may indicate that a Message that was being partially received | This can indicate that a Message that was being partially received | |||
previously, but had not completed, encountered an error and will not | previously, but had not completed, encountered an error and will not | |||
be completed. | be completed. | |||
8.3.3. Receive Message Properties | 8.3.3. Receive Message Properties | |||
Each Message Context may contain metadata from protocols in the | Each Message Context may contain metadata from protocols in the | |||
Protocol Stack; which metadata is available is Protocol Stack | Protocol Stack; which metadata is available is Protocol Stack | |||
dependent. These are exposed though additional read-only Message | dependent. These are exposed though additional read-only Message | |||
Properties that can be queried from the MessageContext object (see | Properties that can be queried from the MessageContext object (see | |||
Section 8.1.1) passed by the receive event. The following metadata | Section 8.1.1) passed by the receive event. The following metadata | |||
values are supported: | values are supported: | |||
8.3.3.1. UDP(-Lite)-specific Property: ECN | 8.3.3.1. UDP(-Lite)-specific Property: ECN | |||
When available, Message metadata carries the value of the Explicit | When available, Message metadata carries the value of the Explicit | |||
Congestion Notification (ECN) field. This information can be used | Congestion Notification (ECN) field. This information can be used | |||
for logging and debugging purposes, and for building applications | for logging and debugging, and for building applications that need | |||
which need access to information about the transport internals for | access to information about the transport internals for their own | |||
their own operation. This property is specific to UDP and UDP-Lite | operation. This property is specific to UDP and UDP-Lite because | |||
because these protocols do not implement congestion control, and | these protocols do not implement congestion control, and hence expose | |||
hence expose this functionality to the application. | this functionality to the application. | |||
8.3.3.2. Early Data | 8.3.3.2. Early Data | |||
In some cases it may be valuable to know whether data was read as | In some cases it can be valuable to know whether data was read as | |||
part of early data transfer (before connection establishment has | part of early data transfer (before connection establishment has | |||
finished). This is useful if applications need to treat early data | finished). This is useful if applications need to treat early data | |||
separately, e.g., if early data has different security properties | separately, e.g., if early data has different security properties | |||
than data sent after connection establishment. In the case of TLS | than data sent after connection establishment. In the case of TLS | |||
1.3, client early data can be replayed maliciously (see [RFC8446]). | 1.3, client early data can be replayed maliciously (see [RFC8446]). | |||
Thus, receivers may wish to perform additional checks for early data | Thus, receivers might wish to perform additional checks for early | |||
to ensure it is safely replayable. If TLS 1.3 is available and the | data to ensure it is safely replayable. If TLS 1.3 is available and | |||
recipient Message was sent as part of early data, the corresponding | the recipient Message was sent as part of early data, the | |||
metadata carries a flag indicating as such. If early data is | corresponding metadata carries a flag indicating as such. If early | |||
enabled, applications should check this metadata field for Messages | data is enabled, applications should check this metadata field for | |||
received during connection establishment and respond accordingly. | Messages received during connection establishment and respond | |||
accordingly. | ||||
8.3.3.3. Receiving Final Messages | 8.3.3.3. Receiving Final Messages | |||
The Message Context can indicate whether or not this Message is the | The Message Context can indicate whether or not this Message is the | |||
Final Message on a Connection. For any Message that is marked as | Final Message on a Connection. For any Message that is marked as | |||
Final, the application can assume that there will be no more Messages | Final, the application can assume that there will be no more Messages | |||
received on the Connection once the Message has been completely | received on the Connection once the Message has been completely | |||
delivered. This corresponds to the Final property that may be marked | delivered. This corresponds to the Final property that may be marked | |||
on a sent Message, see Section 8.1.3.5. | on a sent Message, see Section 8.1.3.5. | |||
Some transport protocols and peers may not support signaling of the | Some transport protocols and peers do not support signaling of the | |||
Final property. Applications therefore should not rely on receiving | Final property. Applications therefore should not rely on receiving | |||
a Message marked Final to know that the other endpoint is done | a Message marked Final to know that the sending endpoint is done | |||
sending on a connection. | sending on a connection. | |||
Any calls to Receive once the Final Message has been delivered will | Any calls to Receive once the Final Message has been delivered will | |||
result in errors. | result in errors. | |||
9. Connection Termination | 9. Connection Termination | |||
Close terminates a Connection after satisfying all the requirements | Close terminates a Connection after satisfying all the requirements | |||
that were specified regarding the delivery of Messages that the | that were specified regarding the delivery of Messages that the | |||
application has already given to the transport system. For example, | application has already given to the transport system. For example, | |||
if reliable delivery was requested for a Message handed over before | if reliable delivery was requested for a Message handed over before | |||
calling Close, the transport system will ensure that this Message is | calling Close, the Closed Event will signify that this Message has | |||
indeed delivered. If the Remote Endpoint still has data to send, it | indeed been delivered. If the Remote Endpoint still has data to | |||
cannot be received after this call. | send, it cannot be received after this call. | |||
Connection.Close() | Connection.Close() | |||
The Closed Event can inform the application that the Remote Endpoint | The Closed Event informs the application that the Remote Endpoint has | |||
has closed the Connection; however, there is no guarantee that a | closed the Connection. There is no guarantee that a remote Close | |||
remote Close will indeed be signaled. | will indeed be signaled. | |||
Connection -> Closed<> | Connection -> Closed<> | |||
Abort terminates a Connection without delivering remaining data: | Abort terminates a Connection without delivering any remaining data: | |||
Connection.Abort() | Connection.Abort() | |||
A ConnectionError informs the application that data to could not be | ||||
delivered after a timeout, or the other side has aborted the | A ConnectionError informs the application that: 1) data could not be | |||
Connection; however, there is no guarantee that an Abort will indeed | delivered to the peer after a timeout, or 2) the Connection has been | |||
be signaled. | aborted (e.g., because the peer has called Abort). There is no | |||
guarantee that an Abort will indeed be signaled. | ||||
Connection -> ConnectionError<reason?> | Connection -> ConnectionError<reason?> | |||
10. Connection State and Ordering of Operations and Events | 10. Connection State and Ordering of Operations and Events | |||
As this interface is designed to be independent of an | This interface is designed to be independent of an implementation's | |||
implementation's concurrency model, the details of how exactly | concurrency model. The details of how exactly actions are handled, | |||
actions are handled, and how events are dispatched, are | and how events are dispatched, are implementation dependent. | |||
implementation dependent. | ||||
Each transition of connection state is associated with one of more | Each transition of connection state is associated with one of more | |||
events: | events: | |||
o Ready<> occurs when a Connection created with Initiate() or | * Ready<> occurs when a Connection created with Initiate() or | |||
InitiateWithSend() transitions to Established state. | InitiateWithSend() transitions to Established state. | |||
o ConnectionReceived<> occurs when a Connection created with | * ConnectionReceived<> occurs when a Connection created with | |||
Listen() transitions to Established state. | Listen() transitions to Established state. | |||
o RendezvousDone<> occurs when a Connection created with | * RendezvousDone<> occurs when a Connection created with | |||
Rendezvous() transitions to Established state. | Rendezvous() transitions to Established state. | |||
o Closed<> occurs when a Connection transitions to Closed state | * Closed<> occurs when a Connection transitions to Closed state | |||
without error. | without error. | |||
o InitiateError<> occurs when a Connection created with Initiate() | * InitiateError<> occurs when a Connection created with Initiate() | |||
transitions from Establishing state to Closed state due to an | transitions from Establishing state to Closed state due to an | |||
error. | error. | |||
o ConnectionError<> occurs when a Connection transitions to Closed | * ConnectionError<> occurs when a Connection transitions to Closed | |||
state due to an error in all other circumstances. | state due to an error in all other circumstances. | |||
The following diagram shows the possible states of a Connection and | The following diagram shows the possible states of a Connection and | |||
the events that occur upon a transition from one state to another. | the events that occur upon a transition from one state to another. | |||
(*) (**) | (*) (**) | |||
Establishing -----> Established -----> Closed | Establishing -----> Established -----> Closed | |||
| ^ | | ^ | |||
| | | | | | |||
+-----------------------------------+ | +-----------------------------------+ | |||
InitiateError<> | InitiateError<> | |||
(*) Ready<>, ConnectionReceived<>, RendezvousDone<> | (*) Ready<>, ConnectionReceived<>, RendezvousDone<> | |||
(**) Closed<>, ConnectionError<> | (**) Closed<>, ConnectionError<> | |||
Figure 1: Connection State Diagram | Figure 2: Connection State Diagram | |||
The interface provides the following guarantees about the ordering of | The interface provides the following guarantees about the ordering of | |||
operations: | operations: | |||
o Sent<> events will occur on a Connection in the order in which the | * Sent<> events will occur on a Connection in the order in which the | |||
Messages were sent (i.e., delivered to the kernel or to the | Messages were sent (i.e., delivered to the kernel or to the | |||
network interface, depending on implementation). | network interface, depending on implementation). | |||
o Received<> will never occur on a Connection before it is | * Received<> will never occur on a Connection before it is | |||
Established; i.e. before a Ready<> event on that Connection, or a | Established; i.e. before a Ready<> event on that Connection, or a | |||
ConnectionReceived<> or RendezvousDone<> containing that | ConnectionReceived<> or RendezvousDone<> containing that | |||
Connection. | Connection. | |||
o No events will occur on a Connection after it is Closed; i.e., | * No events will occur on a Connection after it is Closed; i.e., | |||
after a Closed<> event, an InitiateError<> or ConnectionError<> on | after a Closed<> event, an InitiateError<> or ConnectionError<> | |||
that connection. To ensure this ordering, Closed<> will not occur | will not occur on that connection. To ensure this ordering, | |||
on a Connection while other events on the Connection are still | Closed<> will not occur on a Connection while other events on the | |||
locally outstanding (i.e., known to the interface and waiting to | Connection are still locally outstanding (i.e., known to the | |||
be dealt with by the application). ConnectionError<> may occur | interface and waiting to be dealt with by the application). | |||
after Closed<>, but the interface must gracefully handle all cases | ||||
where application ignores these errors. | ||||
11. IANA Considerations | 11. IANA Considerations | |||
RFC-EDITOR: Please remove this section before publication. | RFC-EDITOR: Please remove this section before publication. | |||
This document has no Actions for IANA. Later versions of this | This document has no Actions for IANA. Later versions of this | |||
document may create IANA registries for generic transport property | document may create IANA registries for generic transport property | |||
names and transport property namespaces (see Section 4.2.1). | names and transport property namespaces (see Section 4.2.1). | |||
12. Security Considerations | 12. Privacy and Security Considerations | |||
This document describes a generic API for interacting with a | This document describes a generic API for interacting with a | |||
transport services (TAPS) system. Part of this API includes | transport services (TAPS) system. Part of this API includes | |||
configuration details for transport security protocols, as discussed | configuration details for transport security protocols, as discussed | |||
in Section 5.3. It does not recommend use (or disuse) of specific | in Section 5.3. It does not recommend use (or disuse) of specific | |||
algorithms or protocols. Any API-compatible transport security | algorithms or protocols. Any API-compatible transport security | |||
protocol should work in a TAPS system. Security consideration for | protocol ought to work in a TAPS system. Security considerations for | |||
these protocols should be discussed in the respective specifications. | these protocols are discussed in the respective specifications. | |||
The desribed API is used to exchange information between an | The described API is used to exchange information between an | |||
application and the transport system. While it is not necessarily | application and the transport system. While it is not necessarily | |||
expected that both systems are implemented by the same authority, it | expected that both systems are implemented by the same authority, it | |||
is expected that the transport system implementation is either | is expected that the transport system implementation is either | |||
provided as a library that is selected by the application from a | provided as a library that is selected by the application from a | |||
trusted party, or that it is part of the operating system that the | trusted party, or that it is part of the operating system that the | |||
application also relies on for other tasks. | application also relies on for other tasks. | |||
In either case, the TAPS API is an internal interface that is used to | In either case, the TAPS API is an internal interface that is used to | |||
change information locally between two systems. However, as the | change information locally between two systems. However, as the | |||
transport system is responsible for network communication, it is in | transport system is responsible for network communication, it is in | |||
the position to potentially share any information provided by the | the position to potentially share any information provided by the | |||
application with the network or another communication peer. Most of | application with the network or another communication peer. Most of | |||
the information provided over the TAPS API are useful to configure | the information provided over the TAPS API are useful to configure | |||
and select protocols and paths and are not necessarily privacy | and select protocols and paths and are not necessarily privacy | |||
sensitive. Still, there is some information that could be privacy | sensitive. Still, some information could be privacy sensitive | |||
sensitve because this might reveal usage characteristics and habits | because it might reveal usage characteristics and habits of the user | |||
of the user of an application. | of an application. | |||
Of course any communication over a network reveals usage | Of course any communication over a network reveals usage | |||
characteristics, as all packets as well as their timing and size are | characteristics, as all packets, as well as their timing and size, | |||
part of the network-visible wire image [RFC8546]. However, the | are part of the network-visible wire image [RFC8546]. However, the | |||
selection of a protocol and its configuration also impacts which | selection of a protocol and its configuration also impacts which | |||
information is visible, potentially in clear text, and which other | information is visible, potentially in clear text, and which other | |||
enties can access it. In most cases information that is provided for | entities can access it. In most cases, information provided for | |||
protocol and path selection should not directly translate to | protocol and path selection should not directly translate to | |||
information that is can be observed by network devices on the path. | information that can be observed by network devices on the path. | |||
But there might be specific configuration information that are | However, there might be specific configuration information that is | |||
intended for path exposure, such as e.g. a DiffServ codepoint | intended for path exposure, e.g., a DiffServ codepoint setting, that | |||
setting, that is either povided directly by the application or | is either provided directly by the application or indirectly | |||
indirectly configured over a traffic profile. | configured for a traffic profile. | |||
Further, applications should be aware that communication attempts can | Applications should be aware that communication attempts can lead to | |||
lead to more than one connection establishment. This is for example | more than one connection establishment. This is the case, for | |||
the case when the transport system also excecutes name resolution; or | example, when the transport system also executes name resolution, | |||
when support mechanisms such as TURN or ICE are used to establish | when support mechanisms such as TURN or ICE are used to establish | |||
connectivity; or if protocols or paths are raised; or if a path fails | connectivity, if protocols or paths are raised, or if a path fails | |||
and fallback or re-establishment is supported in the transport | and fallback or re-establishment is supported in the transport | |||
system. | system. | |||
The interface explicitly does not require the application to resolve | ||||
names, though there is a tradeoff between early and late binding of | ||||
addresses to names. Early binding allows the API implementation to | ||||
reduce connection setup latency, at the cost of potentially limited | ||||
scope for alternate path discovery during Connection establishment, | ||||
as well as potential additional information leakage about application | ||||
interest when used with a resolution method (such as DNS without TLS) | ||||
which does not protect query confidentiality. | ||||
These communication activities are not different from what is used | These communication activities are not different from what is used | |||
today, however, the goal of a TAPS transport system is to support | today. However, the goal of a TAPS transport system is to support | |||
such mechanisms as a generic service within the transport layer. | such mechanisms as a generic service within the transport layer. | |||
This enables applications to more dynamically benefit from | This enables applications to more dynamically benefit from | |||
innovations and new protocols in the transport system but at the same | innovations and new protocols in the transport, although it reduces | |||
time may reduce transparency of the underlying communication actions | transparency of the underlying communication actions to the | |||
to the application itself. The TAPS API is designed such that | application itself. The TAPS API is designed such that protocol and | |||
protocol and path selection can be limited to a small and controlled | path selection can be limited to a small and controlled set if | |||
set if required by the application for functional or security | required by the application for functional or security purposes. | |||
purposes. Further, TAPS implementations should provide an interface | Further, TAPS implementations should provide an interface to poll | |||
to poll information about which protocol and path is currently in use | information about which protocol and path is currently in use as well | |||
as well as provide logging about the communication events of each | as provide logging about the communication events of each connection. | |||
connection. | ||||
13. Acknowledgements | 13. Acknowledgements | |||
This work has received funding from the European Union's Horizon 2020 | This work has received funding from the European Union's Horizon 2020 | |||
research and innovation programme under grant agreements No. 644334 | research and innovation programme under grant agreements No. 644334 | |||
(NEAT) and No. 688421 (MAMI). | (NEAT) and No. 688421 (MAMI). | |||
This work has been supported by Leibniz Prize project funds of DFG - | This work has been supported by Leibniz Prize project funds of DFG - | |||
German Research Foundation: Gottfried Wilhelm Leibniz-Preis 2011 (FKZ | German Research Foundation: Gottfried Wilhelm Leibniz-Preis 2011 (FKZ | |||
FE 570/4-1). | FE 570/4-1). | |||
skipping to change at page 63, line 45 ¶ | skipping to change at page 68, line 36 ¶ | |||
good questions based on implementation experience and for | good questions based on implementation experience and for | |||
contributing text, e.g., on multicast. | contributing text, e.g., on multicast. | |||
14. References | 14. References | |||
14.1. Normative References | 14.1. Normative References | |||
[I-D.ietf-taps-arch] | [I-D.ietf-taps-arch] | |||
Pauly, T., Trammell, B., Brunstrom, A., Fairhurst, G., | Pauly, T., Trammell, B., Brunstrom, A., Fairhurst, G., | |||
Perkins, C., Tiesel, P., and C. Wood, "An Architecture for | Perkins, C., Tiesel, P., and C. Wood, "An Architecture for | |||
Transport Services", draft-ietf-taps-arch-08 (work in | Transport Services", Work in Progress, Internet-Draft, | |||
progress), July 2020. | draft-ietf-taps-arch-08, 13 July 2020, | |||
<http://www.ietf.org/internet-drafts/draft-ietf-taps-arch- | ||||
08.txt>. | ||||
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | |||
Requirement Levels", BCP 14, RFC 2119, | Requirement Levels", BCP 14, RFC 2119, | |||
DOI 10.17487/RFC2119, March 1997, | DOI 10.17487/RFC2119, March 1997, | |||
<https://www.rfc-editor.org/info/rfc2119>. | <https://www.rfc-editor.org/info/rfc2119>. | |||
[RFC2914] Floyd, S., "Congestion Control Principles", BCP 41, | ||||
RFC 2914, DOI 10.17487/RFC2914, September 2000, | ||||
<https://www.rfc-editor.org/info/rfc2914>. | ||||
[RFC4941] Narten, T., Draves, R., and S. Krishnan, "Privacy | [RFC4941] Narten, T., Draves, R., and S. Krishnan, "Privacy | |||
Extensions for Stateless Address Autoconfiguration in | Extensions for Stateless Address Autoconfiguration in | |||
IPv6", RFC 4941, DOI 10.17487/RFC4941, September 2007, | IPv6", RFC 4941, DOI 10.17487/RFC4941, September 2007, | |||
<https://www.rfc-editor.org/info/rfc4941>. | <https://www.rfc-editor.org/info/rfc4941>. | |||
[RFC8084] Fairhurst, G., "Network Transport Circuit Breakers", | ||||
BCP 208, RFC 8084, DOI 10.17487/RFC8084, March 2017, | ||||
<https://www.rfc-editor.org/info/rfc8084>. | ||||
[RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage | ||||
Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, | ||||
March 2017, <https://www.rfc-editor.org/info/rfc8085>. | ||||
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC | [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC | |||
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, | 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, | |||
May 2017, <https://www.rfc-editor.org/info/rfc8174>. | May 2017, <https://www.rfc-editor.org/info/rfc8174>. | |||
[RFC8303] Welzl, M., Tuexen, M., and N. Khademi, "On the Usage of | [RFC8303] Welzl, M., Tuexen, M., and N. Khademi, "On the Usage of | |||
Transport Features Provided by IETF Transport Protocols", | Transport Features Provided by IETF Transport Protocols", | |||
RFC 8303, DOI 10.17487/RFC8303, February 2018, | RFC 8303, DOI 10.17487/RFC8303, February 2018, | |||
<https://www.rfc-editor.org/info/rfc8303>. | <https://www.rfc-editor.org/info/rfc8303>. | |||
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol | [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol | |||
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, | Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, | |||
<https://www.rfc-editor.org/info/rfc8446>. | <https://www.rfc-editor.org/info/rfc8446>. | |||
14.2. Informative References | 14.2. Informative References | |||
[I-D.ietf-httpbis-priority] | ||||
Oku, K. and L. Pardue, "Extensible Prioritization Scheme | ||||
for HTTP", Work in Progress, Internet-Draft, draft-ietf- | ||||
httpbis-priority-02, 1 October 2020, <http://www.ietf.org/ | ||||
internet-drafts/draft-ietf-httpbis-priority-02.txt>. | ||||
[I-D.ietf-taps-impl] | [I-D.ietf-taps-impl] | |||
Brunstrom, A., Pauly, T., Enghardt, T., Grinnemo, K., | Brunstrom, A., Pauly, T., Enghardt, T., Grinnemo, K., | |||
Jones, T., Tiesel, P., Perkins, C., and M. Welzl, | Jones, T., Tiesel, P., Perkins, C., and M. Welzl, | |||
"Implementing Interfaces to Transport Services", draft- | "Implementing Interfaces to Transport Services", Work in | |||
ietf-taps-impl-07 (work in progress), July 2020. | Progress, Internet-Draft, draft-ietf-taps-impl-07, 13 July | |||
2020, <http://www.ietf.org/internet-drafts/draft-ietf- | ||||
[I-D.ietf-taps-minset] | taps-impl-07.txt>. | |||
Welzl, M. and S. Gjessing, "A Minimal Set of Transport | ||||
Services for End Systems", draft-ietf-taps-minset-11 (work | ||||
in progress), September 2018. | ||||
[I-D.ietf-taps-transport-security] | ||||
Enghardt, T., Pauly, T., Perkins, C., Rose, K., and C. | ||||
Wood, "A Survey of the Interaction Between Security | ||||
Protocols and Transport Services", draft-ietf-taps- | ||||
transport-security-12 (work in progress), April 2020. | ||||
[I-D.ietf-tsvwg-datagram-plpmtud] | [I-D.ietf-tsvwg-datagram-plpmtud] | |||
Fairhurst, G., Jones, T., Tuexen, M., Ruengeler, I., and | Fairhurst, G., Jones, T., Tuexen, M., Ruengeler, I., and | |||
T. Voelker, "Packetization Layer Path MTU Discovery for | T. Voelker, "Packetization Layer Path MTU Discovery for | |||
Datagram Transports", draft-ietf-tsvwg-datagram-plpmtud-22 | Datagram Transports", Work in Progress, Internet-Draft, | |||
(work in progress), June 2020. | draft-ietf-tsvwg-datagram-plpmtud-22, 10 June 2020, | |||
<http://www.ietf.org/internet-drafts/draft-ietf-tsvwg- | ||||
datagram-plpmtud-22.txt>. | ||||
[RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, | [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, | |||
"Definition of the Differentiated Services Field (DS | "Definition of the Differentiated Services Field (DS | |||
Field) in the IPv4 and IPv6 Headers", RFC 2474, | Field) in the IPv4 and IPv6 Headers", RFC 2474, | |||
DOI 10.17487/RFC2474, December 1998, | DOI 10.17487/RFC2474, December 1998, | |||
<https://www.rfc-editor.org/info/rfc2474>. | <https://www.rfc-editor.org/info/rfc2474>. | |||
[RFC2597] Heinanen, J., Baker, F., Weiss, W., and J. Wroclawski, | [RFC2597] Heinanen, J., Baker, F., Weiss, W., and J. Wroclawski, | |||
"Assured Forwarding PHB Group", RFC 2597, | "Assured Forwarding PHB Group", RFC 2597, | |||
DOI 10.17487/RFC2597, June 1999, | DOI 10.17487/RFC2597, June 1999, | |||
<https://www.rfc-editor.org/info/rfc2597>. | <https://www.rfc-editor.org/info/rfc2597>. | |||
[RFC2914] Floyd, S., "Congestion Control Principles", BCP 41, | [RFC3246] Davie, B., Charny, A., Bennet, J.C.R., Benson, K., Le | |||
RFC 2914, DOI 10.17487/RFC2914, September 2000, | Boudec, J.Y., Courtney, W., Davari, S., Firoiu, V., and D. | |||
<https://www.rfc-editor.org/info/rfc2914>. | ||||
[RFC3246] Davie, B., Charny, A., Bennet, J., Benson, K., Le Boudec, | ||||
J., Courtney, W., Davari, S., Firoiu, V., and D. | ||||
Stiliadis, "An Expedited Forwarding PHB (Per-Hop | Stiliadis, "An Expedited Forwarding PHB (Per-Hop | |||
Behavior)", RFC 3246, DOI 10.17487/RFC3246, March 2002, | Behavior)", RFC 3246, DOI 10.17487/RFC3246, March 2002, | |||
<https://www.rfc-editor.org/info/rfc3246>. | <https://www.rfc-editor.org/info/rfc3246>. | |||
[RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, | [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, | |||
A., Peterson, J., Sparks, R., Handley, M., and E. | A., Peterson, J., Sparks, R., Handley, M., and E. | |||
Schooler, "SIP: Session Initiation Protocol", RFC 3261, | Schooler, "SIP: Session Initiation Protocol", RFC 3261, | |||
DOI 10.17487/RFC3261, June 2002, | DOI 10.17487/RFC3261, June 2002, | |||
<https://www.rfc-editor.org/info/rfc3261>. | <https://www.rfc-editor.org/info/rfc3261>. | |||
skipping to change at page 65, line 41 ¶ | skipping to change at page 71, line 5 ¶ | |||
[RFC5245] Rosenberg, J., "Interactive Connectivity Establishment | [RFC5245] Rosenberg, J., "Interactive Connectivity Establishment | |||
(ICE): A Protocol for Network Address Translator (NAT) | (ICE): A Protocol for Network Address Translator (NAT) | |||
Traversal for Offer/Answer Protocols", RFC 5245, | Traversal for Offer/Answer Protocols", RFC 5245, | |||
DOI 10.17487/RFC5245, April 2010, | DOI 10.17487/RFC5245, April 2010, | |||
<https://www.rfc-editor.org/info/rfc5245>. | <https://www.rfc-editor.org/info/rfc5245>. | |||
[RFC5482] Eggert, L. and F. Gont, "TCP User Timeout Option", | [RFC5482] Eggert, L. and F. Gont, "TCP User Timeout Option", | |||
RFC 5482, DOI 10.17487/RFC5482, March 2009, | RFC 5482, DOI 10.17487/RFC5482, March 2009, | |||
<https://www.rfc-editor.org/info/rfc5482>. | <https://www.rfc-editor.org/info/rfc5482>. | |||
[RFC5766] Mahy, R., Matthews, P., and J. Rosenberg, "Traversal Using | ||||
Relays around NAT (TURN): Relay Extensions to Session | ||||
Traversal Utilities for NAT (STUN)", RFC 5766, | ||||
DOI 10.17487/RFC5766, April 2010, | ||||
<https://www.rfc-editor.org/info/rfc5766>. | ||||
[RFC5865] Baker, F., Polk, J., and M. Dolly, "A Differentiated | [RFC5865] Baker, F., Polk, J., and M. Dolly, "A Differentiated | |||
Services Code Point (DSCP) for Capacity-Admitted Traffic", | Services Code Point (DSCP) for Capacity-Admitted Traffic", | |||
RFC 5865, DOI 10.17487/RFC5865, May 2010, | RFC 5865, DOI 10.17487/RFC5865, May 2010, | |||
<https://www.rfc-editor.org/info/rfc5865>. | <https://www.rfc-editor.org/info/rfc5865>. | |||
[RFC7478] Holmberg, C., Hakansson, S., and G. Eriksson, "Web Real- | [RFC7478] Holmberg, C., Hakansson, S., and G. Eriksson, "Web Real- | |||
Time Communication Use Cases and Requirements", RFC 7478, | Time Communication Use Cases and Requirements", RFC 7478, | |||
DOI 10.17487/RFC7478, March 2015, | DOI 10.17487/RFC7478, March 2015, | |||
<https://www.rfc-editor.org/info/rfc7478>. | <https://www.rfc-editor.org/info/rfc7478>. | |||
[RFC7556] Anipko, D., Ed., "Multiple Provisioning Domain | [RFC7556] Anipko, D., Ed., "Multiple Provisioning Domain | |||
Architecture", RFC 7556, DOI 10.17487/RFC7556, June 2015, | Architecture", RFC 7556, DOI 10.17487/RFC7556, June 2015, | |||
<https://www.rfc-editor.org/info/rfc7556>. | <https://www.rfc-editor.org/info/rfc7556>. | |||
[RFC7657] Black, D., Ed. and P. Jones, "Differentiated Services | [RFC7657] Black, D., Ed. and P. Jones, "Differentiated Services | |||
(Diffserv) and Real-Time Communication", RFC 7657, | (Diffserv) and Real-Time Communication", RFC 7657, | |||
DOI 10.17487/RFC7657, November 2015, | DOI 10.17487/RFC7657, November 2015, | |||
<https://www.rfc-editor.org/info/rfc7657>. | <https://www.rfc-editor.org/info/rfc7657>. | |||
[RFC8084] Fairhurst, G., "Network Transport Circuit Breakers", | ||||
BCP 208, RFC 8084, DOI 10.17487/RFC8084, March 2017, | ||||
<https://www.rfc-editor.org/info/rfc8084>. | ||||
[RFC8095] Fairhurst, G., Ed., Trammell, B., Ed., and M. Kuehlewind, | [RFC8095] Fairhurst, G., Ed., Trammell, B., Ed., and M. Kuehlewind, | |||
Ed., "Services Provided by IETF Transport Protocols and | Ed., "Services Provided by IETF Transport Protocols and | |||
Congestion Control Mechanisms", RFC 8095, | Congestion Control Mechanisms", RFC 8095, | |||
DOI 10.17487/RFC8095, March 2017, | DOI 10.17487/RFC8095, March 2017, | |||
<https://www.rfc-editor.org/info/rfc8095>. | <https://www.rfc-editor.org/info/rfc8095>. | |||
[RFC8229] Pauly, T., Touati, S., and R. Mantha, "TCP Encapsulation | [RFC8229] Pauly, T., Touati, S., and R. Mantha, "TCP Encapsulation | |||
of IKE and IPsec Packets", RFC 8229, DOI 10.17487/RFC8229, | of IKE and IPsec Packets", RFC 8229, DOI 10.17487/RFC8229, | |||
August 2017, <https://www.rfc-editor.org/info/rfc8229>. | August 2017, <https://www.rfc-editor.org/info/rfc8229>. | |||
[RFC8260] Stewart, R., Tuexen, M., Loreto, S., and R. Seggelmann, | [RFC8260] Stewart, R., Tuexen, M., Loreto, S., and R. Seggelmann, | |||
"Stream Schedulers and User Message Interleaving for the | "Stream Schedulers and User Message Interleaving for the | |||
Stream Control Transmission Protocol", RFC 8260, | Stream Control Transmission Protocol", RFC 8260, | |||
DOI 10.17487/RFC8260, November 2017, | DOI 10.17487/RFC8260, November 2017, | |||
<https://www.rfc-editor.org/info/rfc8260>. | <https://www.rfc-editor.org/info/rfc8260>. | |||
[RFC8489] Petit-Huguenin, M., Salgueiro, G., Rosenberg, J., Wing, | ||||
D., Mahy, R., and P. Matthews, "Session Traversal | ||||
Utilities for NAT (STUN)", RFC 8489, DOI 10.17487/RFC8489, | ||||
February 2020, <https://www.rfc-editor.org/info/rfc8489>. | ||||
[RFC8546] Trammell, B. and M. Kuehlewind, "The Wire Image of a | [RFC8546] Trammell, B. and M. Kuehlewind, "The Wire Image of a | |||
Network Protocol", RFC 8546, DOI 10.17487/RFC8546, April | Network Protocol", RFC 8546, DOI 10.17487/RFC8546, April | |||
2019, <https://www.rfc-editor.org/info/rfc8546>. | 2019, <https://www.rfc-editor.org/info/rfc8546>. | |||
[RFC8622] Bless, R., "A Lower-Effort Per-Hop Behavior (LE PHB) for | [RFC8622] Bless, R., "A Lower-Effort Per-Hop Behavior (LE PHB) for | |||
Differentiated Services", RFC 8622, DOI 10.17487/RFC8622, | Differentiated Services", RFC 8622, DOI 10.17487/RFC8622, | |||
June 2019, <https://www.rfc-editor.org/info/rfc8622>. | June 2019, <https://www.rfc-editor.org/info/rfc8622>. | |||
[RFC8699] Islam, S., Welzl, M., and S. Gjessing, "Coupled Congestion | [RFC8699] Islam, S., Welzl, M., and S. Gjessing, "Coupled Congestion | |||
Control for RTP Media", RFC 8699, DOI 10.17487/RFC8699, | Control for RTP Media", RFC 8699, DOI 10.17487/RFC8699, | |||
January 2020, <https://www.rfc-editor.org/info/rfc8699>. | January 2020, <https://www.rfc-editor.org/info/rfc8699>. | |||
[RFC8922] Enghardt, T., Pauly, T., Perkins, C., Rose, K., and C. | ||||
Wood, "A Survey of the Interaction between Security | ||||
Protocols and Transport Services", RFC 8922, | ||||
DOI 10.17487/RFC8922, October 2020, | ||||
<https://www.rfc-editor.org/info/rfc8922>. | ||||
[RFC8923] Welzl, M. and S. Gjessing, "A Minimal Set of Transport | ||||
Services for End Systems", RFC 8923, DOI 10.17487/RFC8923, | ||||
October 2020, <https://www.rfc-editor.org/info/rfc8923>. | ||||
[TCP-COUPLING] | [TCP-COUPLING] | |||
"ctrlTCP: Reducing Latency through Coupled, Heterogeneous | "ctrlTCP: Reducing Latency through Coupled, Heterogeneous | |||
Multi-Flow TCP Congestion Control", IEEE INFOCOM Global | Multi-Flow TCP Congestion Control", IEEE INFOCOM Global | |||
Internet Symposium (GI) workshop (GI 2018) , April 2018. | Internet Symposium (GI) workshop (GI 2018) , 15 April | |||
2018. | ||||
Appendix A. Convenience Functions | Appendix A. Convenience Functions | |||
A.1. Adding Preference Properties | A.1. Adding Preference Properties | |||
As Selection Properties of type "Preference" will be added to a | As Selection Properties of type "Preference" will be set on a | |||
TransportProperties object quite frequently, implementations should | TransportProperties object quite frequently, implementations should | |||
provide special actions for adding each preference level i.e, | provide special actions for adding each preference level i.e, | |||
"TransportProperties.Add(some_property, avoid)" is equivalent to | "TransportProperties.Set(some_property, avoid)" is equivalent to | |||
"TransportProperties.Avoid(some_property)": | "TransportProperties.Avoid(some_property)": | |||
TransportProperties.Require(property) | TransportProperties.Require(property) | |||
TransportProperties.Prefer(property) | TransportProperties.Prefer(property) | |||
TransportProperties.Ignore(property) | TransportProperties.Ignore(property) | |||
TransportProperties.Avoid(property) | TransportProperties.Avoid(property) | |||
TransportProperties.Prohibit(property) | TransportProperties.Prohibit(property) | |||
TransportProperties.Default(property) | TransportProperties.Default(property) | |||
A.2. Transport Property Profiles | A.2. Transport Property Profiles | |||
To ease the use of the interface specified by this document, | To ease the use of the interface specified by this document, | |||
implementations should provide a mechanism to create Transport | implementations should provide a mechanism to create Transport | |||
Property objects (see Section 5.2) that are pre-configured with | Property objects (see Section 5.2) that are pre-configured with | |||
frequently used sets of properties. Implementations should at least | frequently used sets of properties. Implementations should at least | |||
offer short-hands to specify the following property profiles: | offer short-hands to specify the following property profiles: | |||
A.2.1. reliable-inorder-stream | A.2.1. reliable-inorder-stream | |||
This profile provides reliable, in-order transport service with | This profile provides reliable, in-order transport service with | |||
congestion control. An example of a protocol that provides this | congestion control. TCP is an example of a protocol that provides | |||
service is TCP. It should consist of the following properties: | this service. It should consist of the following properties: | |||
+-----------------------+---------+ | +=======================+=========+ | |||
| Property | Value | | | Property | Value | | |||
+-----------------------+---------+ | +=======================+=========+ | |||
| reliability | require | | | reliability | require | | |||
| | | | +-----------------------+---------+ | |||
| preserveOrder | require | | | preserveOrder | require | | |||
| | | | +-----------------------+---------+ | |||
| congestionControl | require | | | congestionControl | require | | |||
| | | | +-----------------------+---------+ | |||
| preserveMsgBoundaries | ignore | | | preserveMsgBoundaries | ignore | | |||
+-----------------------+---------+ | +-----------------------+---------+ | |||
Table 2 | ||||
A.2.2. reliable-message | A.2.2. reliable-message | |||
This profile provides message-preserving, reliable, in-order | This profile provides message-preserving, reliable, in-order | |||
transport service with congestion control. An example of a protocol | transport service with congestion control. SCTP is an example of a | |||
that provides this service is SCTP. It should consist of the | protocol that provides this service. It should consist of the | |||
following properties: | following properties: | |||
+-----------------------+---------+ | +=======================+=========+ | |||
| Property | Value | | | Property | Value | | |||
+-----------------------+---------+ | +=======================+=========+ | |||
| reliability | require | | | reliability | require | | |||
| | | | +-----------------------+---------+ | |||
| preserveOrder | require | | | preserveOrder | require | | |||
| | | | +-----------------------+---------+ | |||
| congestionControl | require | | | congestionControl | require | | |||
| | | | +-----------------------+---------+ | |||
| preserveMsgBoundaries | require | | | preserveMsgBoundaries | require | | |||
+-----------------------+---------+ | +-----------------------+---------+ | |||
Table 3 | ||||
A.2.3. unreliable-datagram | A.2.3. unreliable-datagram | |||
This profile provides unreliable datagram transport service. An | This profile provides unreliable datagram transport service. An | |||
example of a protocol that provides this service is UDP. It should | example of a protocol that provides this service is UDP. It consists | |||
consist of the following properties: | of the following properties: | |||
+-----------------------+---------+ | +=======================+=========+ | |||
| Property | Value | | | Property | Value | | |||
+-----------------------+---------+ | +=======================+=========+ | |||
| reliability | ignore | | | reliability | ignore | | |||
| | | | +-----------------------+---------+ | |||
| preserveOrder | ignore | | | preserveOrder | ignore | | |||
| | | | +-----------------------+---------+ | |||
| congestionControl | ignore | | | congestionControl | ignore | | |||
| | | | +-----------------------+---------+ | |||
| preserveMsgBoundaries | require | | | preserveMsgBoundaries | require | | |||
| | | | +-----------------------+---------+ | |||
| safely replayable | true | | | safely replayable | true | | |||
+-----------------------+---------+ | +-----------------------+---------+ | |||
Table 4 | ||||
Applications that choose this Transport Property Profile for latency | Applications that choose this Transport Property Profile for latency | |||
reasons should also consider setting the Capacity Profile Property, | reasons should also consider setting an appropriate Capacity Profile | |||
see Section 7.1.6 accordingly and my benefit from controlling | Property, see Section 7.1.6 and could benefit from controlling | |||
checksum coverage, see Section 5.2.7 and Section 5.2.8. | checksum coverage, see Section 5.2.7 and Section 5.2.8. | |||
Appendix B. Relationship to the Minimal Set of Transport Services for | Appendix B. Relationship to the Minimal Set of Transport Services for | |||
End Systems | End Systems | |||
[I-D.ietf-taps-minset] identifies a minimal set of transport services | [RFC8923] identifies a minimal set of transport services that end | |||
that end systems should offer. These services make all non-security- | systems should offer. These services make all non-security-related | |||
related transport features of TCP, MPTCP, UDP, UDP-Lite, SCTP and | transport features of TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT | |||
LEDBAT available that 1) require interaction with the application, | available that 1) require interaction with the application, and 2) do | |||
and 2) do not get in the way of a possible implementation over TCP | not get in the way of a possible implementation over TCP (or, with | |||
(or, with limitations, UDP). The following text explains how this | limitations, UDP). The following text explains how this minimal set | |||
minimal set is reflected in the present API. For brevity, it is | is reflected in the present API. For brevity, it is based on the | |||
based on the list in Section 4.1 of [I-D.ietf-taps-minset], updated | list in Section 4.1 of [RFC8923], updated according to the discussion | |||
according to the discussion in Section 5 of [I-D.ietf-taps-minset]. | in Section 5 of [RFC8923]. The present API covers all elements of | |||
This list is a subset of the transport features in Appendix A of | this section except "Notification of Excessive Retransmissions (early | |||
[I-D.ietf-taps-minset], which refers to the primitives in "pass 2" | warning below abortion threshold)". This list is a subset of the | |||
(Section 4) of [RFC8303] for further details on the implementation | transport features in Appendix A of [RFC8923], which refers to the | |||
with TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT. | primitives in "pass 2" (Section 4) of [RFC8303] for further details | |||
on the implementation with TCP, MPTCP, UDP, UDP-Lite, SCTP and | ||||
LEDBAT. | ||||
o Connect: "Initiate" Action (Section 6.1). | * Connect: "Initiate" Action (Section 6.1). | |||
o Listen: "Listen" Action (Section 6.2). | * Listen: "Listen" Action (Section 6.2). | |||
o Specify number of attempts and/or timeout for the first | * Specify number of attempts and/or timeout for the first | |||
establishment message: "timeout" parameter of "Initiate" | establishment message: "timeout" parameter of "Initiate" | |||
(Section 6.1) or "InitiateWithSend" Action (Section 8.2.6). | (Section 6.1) or "InitiateWithSend" Action (Section 8.2.5). | |||
o Disable MPTCP: "Parallel Use of Multiple Paths" Property | * Disable MPTCP: "Parallel Use of Multiple Paths" Property | |||
(Section 5.2.13). | (Section 5.2.14). | |||
o Hand over a message to reliably transfer (possibly multiple times) | * Hand over a message to reliably transfer (possibly multiple times) | |||
before connection establishment: "InitiateWithSend" Action | before connection establishment: "InitiateWithSend" Action | |||
(Section 8.2.6). | (Section 8.2.5). | |||
o Change timeout for aborting connection (using retransmit limit or | * Change timeout for aborting connection (using retransmit limit or | |||
time value): "Timeout for Aborting Connection" property, using a | time value): "Timeout for Aborting Connection" property, using a | |||
time value (Section 7.1.4). | time value (Section 7.1.3). | |||
o Timeout event when data could not be delivered for too long: | * Timeout event when data could not be delivered for too long: | |||
"ConnectionError" Event (Section 9). | "ConnectionError" Event (Section 9). | |||
o Suggest timeout to the peer: "TCP-specific Property: User Timeout" | * Suggest timeout to the peer: "TCP-specific Property: User Timeout" | |||
(Section 7.2). | (Section 7.2). | |||
o Notification of Excessive Retransmissions (early warning below | * Notification of ICMP error message arrival: "Notification of ICMP | |||
abortion threshold): "Notification of excessive retransmissions" | ||||
property (Section 5.2.16). | ||||
o Notification of ICMP error message arrival: "Notification of ICMP | ||||
soft error message arrival" property (Section 5.2.17). | soft error message arrival" property (Section 5.2.17). | |||
o Choose a scheduler to operate between streams of an association: | * Choose a scheduler to operate between streams of an association: | |||
"Connection Group Transmission Scheduler" property | "Connection Group Transmission Scheduler" property | |||
(Section 7.1.5). | (Section 7.1.5). | |||
o Configure priority or weight for a scheduler: "Priority | * Configure priority or weight for a scheduler: "Connection | |||
(Connection)" property (Section 7.1.3). | Priority" property (Section 7.1.2). | |||
o "Specify checksum coverage used by the sender" and "Disable | * "Specify checksum coverage used by the sender" and "Disable | |||
checksum when sending": "Corruption Protection Length" property | checksum when sending": "Corruption Protection Length" property | |||
(Section 8.1.3.6) and "Full Checksum Coverage on Sending" property | (Section 8.1.3.6) and "Full Checksum Coverage on Sending" property | |||
(Section 5.2.7). | (Section 5.2.7). | |||
o "Specify minimum checksum coverage required by receiver" and | * "Specify minimum checksum coverage required by receiver" and | |||
"Disable checksum requirement when receiving": "Required Minimum | "Disable checksum requirement when receiving": "Required Minimum | |||
Corruption Protection Coverage for Receiving" property | Corruption Protection Coverage for Receiving" property | |||
(Section 7.1.2) and "Full Checksum Coverage on Receiving" property | (Section 7.1.1) and "Full Checksum Coverage on Receiving" property | |||
(Section 5.2.8). | (Section 5.2.8). | |||
o "Specify DF" field and "Request not to bundle messages": the "No | * "Specify DF field": "No Network-Layer Fragmentation" property | |||
Fragmentation" Message Property combines both of these requests, | (Section 8.1.3.9). | |||
i.e. if a request not to bundle messages is made, this also turns | ||||
off fragmentation (i.e., sets DF=1) in the case of a protocol that | ||||
allows this (only UDP and UDP-Lite, which cannot bundle messages | ||||
anyway) (Section 8.1.3.9). | ||||
o Get max. transport-message size that may be sent using a non- | * "Request not to bundle messages": "No Transport-Layer | |||
Fragmentation" property (Section 8.1.3.10). | ||||
* Get max. transport-message size that may be sent using a non- | ||||
fragmented IP packet from the configured interface: "Maximum | fragmented IP packet from the configured interface: "Maximum | |||
Message Size Before Fragmentation or Segmentation" property | Message Size Before Fragmentation or Segmentation" property | |||
(Section 7.1.9.2). | (Section 7.1.10.2). | |||
o Get max. transport-message size that may be received from the | * Get max. transport-message size that may be received from the | |||
configured interface: "Maximum Message Size on Receive" property | configured interface: "Maximum Message Size on Receive" property | |||
(Section 7.1.9.4). | (Section 7.1.10.4). | |||
o Obtain ECN field: "ECN" is a defined UDP(-Lite)-specific read-only | * Obtain ECN field: "ECN" is a defined UDP(-Lite)-specific read-only | |||
Message Property of the MessageContext object (Section 8.3.3.1). | Message Property of the MessageContext object (Section 8.3.3.1). | |||
o "Specify DSCP field", "Disable Nagle algorithm", "Enable and | * "Specify DSCP field", "Disable Nagle algorithm", "Enable and | |||
configure a "Low Extra Delay Background Transfer"": as suggested | configure a "Low Extra Delay Background Transfer"": as suggested | |||
in Section 5.5 of [I-D.ietf-taps-minset], these transport features | in Section 5.5 of [RFC8923], these transport features are | |||
are collectively offered via the "Capacity Profile" property | collectively offered via the "Capacity Profile" property | |||
(Section 7.1.6). Per-Message control is offered via the "Message | (Section 7.1.6). Per-Message control is offered via the "Message | |||
Capacity Profile Override" property (Section 8.1.3.8). | Capacity Profile Override" property (Section 8.1.3.8). | |||
o Close after reliably delivering all remaining data, causing an | * Close after reliably delivering all remaining data, causing an | |||
event informing the application on the other side: this is offered | event informing the application on the other side: this is offered | |||
by the "Close" Action with slightly changed semantics in line with | by the "Close" Action with slightly changed semantics in line with | |||
the discussion in Section 5.2 of [I-D.ietf-taps-minset] | the discussion in Section 5.2 of [RFC8923] (Section 9). | |||
(Section 9). | ||||
o "Abort without delivering remaining data, causing an event | * "Abort without delivering remaining data, causing an event | |||
informing the application on the other side" and "Abort without | informing the application on the other side" and "Abort without | |||
delivering remaining data, not causing an event informing the | delivering remaining data, not causing an event informing the | |||
application on the other side": this is offered by the "Abort" | application on the other side": this is offered by the "Abort" | |||
action without promising that this is signaled to the other side. | action without promising that this is signaled to the other side. | |||
If it is, a "ConnectionError" Event will fire at the peer | If it is, a "ConnectionError" Event will fire at the peer | |||
(Section 9). | (Section 9). | |||
o "Reliably transfer data, with congestion control", "Reliably | * "Reliably transfer data, with congestion control", "Reliably | |||
transfer a message, with congestion control" and "Unreliably | transfer a message, with congestion control" and "Unreliably | |||
transfer a message": data is transferred via the "Send" action | transfer a message": data is transferred via the "Send" action | |||
(Section 8.2). Reliability is controlled via the "Reliable Data | (Section 8.2). Reliability is controlled via the "Reliable Data | |||
Transfer (Connection)" (Section 5.2.1) property and the "Reliable | Transfer (Connection)" (Section 5.2.1) property and the "Reliable | |||
Data Transfer (Message)" Message Property (Section 8.1.3.7). | Data Transfer (Message)" Message Property (Section 8.1.3.7). | |||
Transmitting data as a message or without delimiters is controlled | Transmitting data as a message or without delimiters is controlled | |||
via Message Framers (Section 8.1.2). The choice of congestion | via Message Framers (Section 8.1.2). The choice of congestion | |||
control is provided via the "Congestion control" property | control is provided via the "Congestion control" property | |||
(Section 5.2.9). | (Section 5.2.9). | |||
o Configurable Message Reliability: the "Lifetime" Message Property | * Configurable Message Reliability: the "Lifetime" Message Property | |||
implements a time-based way to configure message reliability | implements a time-based way to configure message reliability | |||
(Section 8.1.3.1). | (Section 8.1.3.1). | |||
o "Ordered message delivery (potentially slower than unordered)" and | * "Ordered message delivery (potentially slower than unordered)" and | |||
"Unordered message delivery (potentially faster than ordered)": | "Unordered message delivery (potentially faster than ordered)": | |||
these two transport features are controlled via the Message | these two transport features are controlled via the Message | |||
Property "Ordered" (Section 8.1.3.3). | Property "Ordered" (Section 8.1.3.3). | |||
o Request not to delay the acknowledgement (SACK) of a message: | * Request not to delay the acknowledgement (SACK) of a message: | |||
should the protocol support it, this is one of the transport | should the protocol support it, this is one of the transport | |||
features the transport system can apply when an application uses | features the transport system can apply when an application uses | |||
the "Capacity Profile" Property (Section 7.1.6) or the "Message | the "Capacity Profile" Property (Section 7.1.6) or the "Message | |||
Capacity Profile Override" Message Property (Section 8.1.3.8) with | Capacity Profile Override" Message Property (Section 8.1.3.8) with | |||
value "Low Latency/Interactive". | value "Low Latency/Interactive". | |||
o Receive data (with no message delimiting): "Received" Event | * Receive data (with no message delimiting): "Received" Event | |||
(Section 8.3.2.1). See Section 8.1.2 for handling Message framing | (Section 8.3.2.1). See Section 8.1.2 for handling Message framing | |||
in situations where the Protocol Stack only provides a byte-stream | in situations where the Protocol Stack only provides a byte-stream | |||
transport. | transport. | |||
o Receive a message: "Received" Event (Section 8.3.2.1), using | * Receive a message: "Received" Event (Section 8.3.2.1), using | |||
Message Framers (Section 8.1.2). | Message Framers (Section 8.1.2). | |||
o Information about partial message arrival: "ReceivedPartial" Event | * Information about partial message arrival: "ReceivedPartial" Event | |||
(Section 8.3.2.2). | (Section 8.3.2.2). | |||
o Notification of send failures: "Expired" Event (Section 8.2.3.2) | * Notification of send failures: "Expired" Event (Section 8.2.2.2) | |||
and "SendError" Event (Section 8.2.3.3). | and "SendError" Event (Section 8.2.2.3). | |||
o Notification that the stack has no more user data to send: | * Notification that the stack has no more user data to send: | |||
applications can obtain this information via the "Sent" Event | applications can obtain this information via the "Sent" Event | |||
(Section 8.2.3.1). | (Section 8.2.2.1). | |||
o Notification to a receiver that a partial message delivery has | * Notification to a receiver that a partial message delivery has | |||
been aborted: "ReceiveError" Event (Section 8.3.2.3). | been aborted: "ReceiveError" Event (Section 8.3.2.3). | |||
Authors' Addresses | Authors' Addresses | |||
Brian Trammell (editor) | Brian Trammell (editor) | |||
Google Switzerland GmbH | Google Switzerland GmbH | |||
Gustav-Gull-Platz 1 | Gustav-Gull-Platz 1 | |||
8004 Zurich | CH- 8004 Zurich | |||
Switzerland | Switzerland | |||
Email: ietf@trammell.ch | Email: ietf@trammell.ch | |||
Michael Welzl (editor) | Michael Welzl (editor) | |||
University of Oslo | University of Oslo | |||
PO Box 1080 Blindern | PO Box 1080 Blindern | |||
0316 Oslo | 0316 Oslo | |||
Norway | Norway | |||
Email: michawe@ifi.uio.no | Email: michawe@ifi.uio.no | |||
Theresa Enghardt | Theresa Enghardt | |||
Netflix | Netflix | |||
skipping to change at page 72, line 29 ¶ | skipping to change at page 78, line 15 ¶ | |||
University of Oslo | University of Oslo | |||
PO Box 1080 Blindern | PO Box 1080 Blindern | |||
0316 Oslo | 0316 Oslo | |||
Norway | Norway | |||
Email: michawe@ifi.uio.no | Email: michawe@ifi.uio.no | |||
Theresa Enghardt | Theresa Enghardt | |||
Netflix | Netflix | |||
121 Albright Way | 121 Albright Way | |||
Los Gatos, CA 95032 | Los Gatos, CA 95032, | |||
United States of America | United States of America | |||
Email: ietf@tenghardt.net | Email: ietf@tenghardt.net | |||
Godred Fairhurst | Godred Fairhurst | |||
University of Aberdeen | University of Aberdeen | |||
Fraser Noble Building | Fraser Noble Building | |||
Aberdeen, AB24 3UE | Aberdeen, AB24 3UE | |||
Scotland | ||||
Email: gorry@erg.abdn.ac.uk | Email: gorry@erg.abdn.ac.uk | |||
URI: http://www.erg.abdn.ac.uk/ | URI: http://www.erg.abdn.ac.uk/ | |||
Mirja Kuehlewind | Mirja Kuehlewind | |||
Ericsson | Ericsson | |||
Ericsson-Allee 1 | Ericsson-Allee 1 | |||
Herzogenrath | Herzogenrath | |||
Germany | Germany | |||
Email: mirja.kuehlewind@ericsson.com | Email: mirja.kuehlewind@ericsson.com | |||
Colin Perkins | Colin Perkins | |||
University of Glasgow | University of Glasgow | |||
skipping to change at page 73, line 31 ¶ | skipping to change at page 79, line 12 ¶ | |||
TU Berlin | TU Berlin | |||
Einsteinufer 25 | Einsteinufer 25 | |||
10587 Berlin | 10587 Berlin | |||
Germany | Germany | |||
Email: philipp@tiesel.net | Email: philipp@tiesel.net | |||
Christopher A. Wood | Christopher A. Wood | |||
Cloudflare | Cloudflare | |||
101 Townsend St | 101 Townsend St | |||
San Francisco | San Francisco, | |||
United States of America | United States of America | |||
Email: caw@heapingbits.net | Email: caw@heapingbits.net | |||
Tommy Pauly | Tommy Pauly | |||
Apple Inc. | Apple Inc. | |||
One Apple Park Way | One Apple Park Way | |||
Cupertino, California 95014 | Cupertino, California 95014, | |||
United States of America | United States of America | |||
Email: tpauly@apple.com | Email: tpauly@apple.com | |||
End of changes. 384 change blocks. | ||||
939 lines changed or deleted | 1173 lines changed or added | |||
This html diff was produced by rfcdiff 1.46. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ |