draft-ietf-taps-interface-07.txt   draft-ietf-taps-interface-08.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: 14 January 2021 University of Oslo Expires: January 28, 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.A. Wood C. Wood
Cloudflare Cloudflare
T. Pauly T. Pauly
Apple Inc. Apple Inc.
13 July 2020 July 27, 2020
An Abstract Application Layer Interface to Transport Services An Abstract Application Layer Interface to Transport Services
draft-ietf-taps-interface-07 draft-ietf-taps-interface-08
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 10 skipping to change at page 2, line 7
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 14 January 2021. This Internet-Draft will expire on January 28, 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 (https://trustee.ietf.org/ Provisions Relating to IETF Documents
license-info) in effect on the date of publication of this document. (https://trustee.ietf.org/license-info) in effect on the date of
Please review these documents carefully, as they describe your rights publication of this document. Please review these documents
and restrictions with respect to this document. Code Components carefully, as they describe your rights and restrictions with respect
extracted from this document must include Simplified BSD License text to this document. Code Components extracted from this document must
as described in Section 4.e of the Trust Legal Provisions and are include Simplified BSD License text as described in Section 4.e of
provided without warranty as described in the Simplified BSD License. the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Terminology and Notation . . . . . . . . . . . . . . . . . . 5 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 5
3. Overview of Interface Design . . . . . . . . . . . . . . . . 7 3. Overview of Interface Design . . . . . . . . . . . . . . . . 6
4. API Summary . . . . . . . . . . . . . . . . . . . . . . . . . 7 4. API Summary . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.1. Usage Examples . . . . . . . . . . . . . . . . . . . . . 8 4.1. Usage Examples . . . . . . . . . . . . . . . . . . . . . 8
4.1.1. Server Example . . . . . . . . . . . . . . . . . . . 9 4.1.1. Server Example . . . . . . . . . . . . . . . . . . . 8
4.1.2. Client Example . . . . . . . . . . . . . . . . . . . 10 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 . . . . . . . . . . . . . . . . . . 15
5.2. Specifying Transport Properties . . . . . . . . . . . . . 18 5.2. Specifying Transport Properties . . . . . . . . . . . . . 18
5.2.1. Reliable Data Transfer (Connection) . . . . . . . . . 20 5.2.1. Reliable Data Transfer (Connection) . . . . . . . . . 20
5.2.2. Preservation of Message Boundaries . . . . . . . . . 21 5.2.2. Preservation of Message Boundaries . . . . . . . . . 20
5.2.3. Configure Per-Message Reliability . . . . . . . . . . 21 5.2.3. Configure Per-Message Reliability . . . . . . . . . . 21
5.2.4. Preservation of Data Ordering . . . . . . . . . . . . 21 5.2.4. Preservation of Data Ordering . . . . . . . . . . . . 21
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 . . . . . . . . . . . . . . . . . 21
5.2.6. Multistream Connections in Group . . . . . . . . . . 22 5.2.6. Multistream Connections in Group . . . . . . . . . . 22
5.2.7. Full Checksum Coverage on Sending . . . . . . . . . . 22 5.2.7. Full Checksum Coverage on Sending . . . . . . . . . . 22
5.2.8. Full Checksum Coverage on Receiving . . . . . . . . . 22 5.2.8. Full Checksum Coverage on Receiving . . . . . . . . . 22
5.2.9. Congestion control . . . . . . . . . . . . . . . . . 22 5.2.9. Congestion control . . . . . . . . . . . . . . . . . 22
5.2.10. Interface Instance or Type . . . . . . . . . . . . . 23 5.2.10. Interface Instance or Type . . . . . . . . . . . . . 23
5.2.11. Provisioning Domain Instance or Type . . . . . . . . 24 5.2.11. Provisioning Domain Instance or Type . . . . . . . . 24
5.2.12. Use Temporary Local Address . . . . . . . . . . . . . 24 5.2.12. Use Temporary Local Address . . . . . . . . . . . . . 24
5.2.13. Multi-Paths Transport . . . . . . . . . . . . . . . . 25 5.2.13. Multi-Paths Transport . . . . . . . . . . . . . . . . 25
5.2.14. Advertisement of Alternative Addresses . . . . . . . 26 5.2.14. Advertisement of Alternative Addresses . . . . . . . 26
5.2.15. Direction of communication . . . . . . . . . . . . . 26 5.2.15. Direction of communication . . . . . . . . . . . . . 26
5.2.16. Notification of excessive retransmissions . . . . . . 27 5.2.16. Notification of excessive retransmissions . . . . . . 27
5.2.17. Notification of ICMP soft error message arrival . . . 27 5.2.17. Notification of ICMP soft error message arrival . . . 27
5.2.18. Initiating side is not the first to write . . . . . . 27 5.2.18. Initiating side is not the first to write . . . . . . 27
5.3. Specifying Security Parameters and Callbacks . . . . . . 28 5.3. Specifying Security Parameters and Callbacks . . . . . . 28
5.3.1. Pre-Connection Parameters . . . . . . . . . . . . . . 28 5.3.1. Pre-Connection Parameters . . . . . . . . . . . . . . 28
5.3.2. Connection Establishment Callbacks . . . . . . . . . 29 5.3.2. Connection Establishment Callbacks . . . . . . . . . 29
6. Establishing Connections . . . . . . . . . . . . . . . . . . 30 6. Establishing Connections . . . . . . . . . . . . . . . . . . 29
6.1. Active Open: Initiate . . . . . . . . . . . . . . . . . . 30 6.1. Active Open: Initiate . . . . . . . . . . . . . . . . . . 30
6.2. Passive Open: Listen . . . . . . . . . . . . . . . . . . 31 6.2. Passive Open: Listen . . . . . . . . . . . . . . . . . . 31
6.3. Peer-to-Peer Establishment: Rendezvous . . . . . . . . . 32 6.3. Peer-to-Peer Establishment: Rendezvous . . . . . . . . . 32
6.4. Connection Groups . . . . . . . . . . . . . . . . . . . . 34 6.4. Connection Groups . . . . . . . . . . . . . . . . . . . . 33
7. Sending Data . . . . . . . . . . . . . . . . . . . . . . . . 35 7. Sending Data . . . . . . . . . . . . . . . . . . . . . . . . 35
7.1. Basic Sending . . . . . . . . . . . . . . . . . . . . . . 36 7.1. Basic Sending . . . . . . . . . . . . . . . . . . . . . . 35
7.2. Sending Replies . . . . . . . . . . . . . . . . . . . . . 36 7.2. Sending Replies . . . . . . . . . . . . . . . . . . . . . 36
7.3. Send Events . . . . . . . . . . . . . . . . . . . . . . . 37 7.3. Send Events . . . . . . . . . . . . . . . . . . . . . . . 36
7.3.1. Sent . . . . . . . . . . . . . . . . . . . . . . . . 37 7.3.1. Sent . . . . . . . . . . . . . . . . . . . . . . . . 37
7.3.2. Expired . . . . . . . . . . . . . . . . . . . . . . . 37 7.3.2. Expired . . . . . . . . . . . . . . . . . . . . . . . 37
7.3.3. SendError . . . . . . . . . . . . . . . . . . . . . . 38 7.3.3. SendError . . . . . . . . . . . . . . . . . . . . . . 37
7.4. Message Contexts . . . . . . . . . . . . . . . . . . . . 38 7.4. Message Contexts . . . . . . . . . . . . . . . . . . . . 37
7.5. Message Properties . . . . . . . . . . . . . . . . . . . 38 7.5. Message Properties . . . . . . . . . . . . . . . . . . . 38
7.5.1. Lifetime . . . . . . . . . . . . . . . . . . . . . . 40 7.5.1. Lifetime . . . . . . . . . . . . . . . . . . . . . . 39
7.5.2. Priority . . . . . . . . . . . . . . . . . . . . . . 40 7.5.2. Priority . . . . . . . . . . . . . . . . . . . . . . 40
7.5.3. Ordered . . . . . . . . . . . . . . . . . . . . . . . 40 7.5.3. Ordered . . . . . . . . . . . . . . . . . . . . . . . 40
7.5.4. Safely Replayable . . . . . . . . . . . . . . . . . . 41 7.5.4. Safely Replayable . . . . . . . . . . . . . . . . . . 41
7.5.5. Final . . . . . . . . . . . . . . . . . . . . . . . . 41 7.5.5. Final . . . . . . . . . . . . . . . . . . . . . . . . 41
7.5.6. Corruption Protection Length . . . . . . . . . . . . 42 7.5.6. Corruption Protection Length . . . . . . . . . . . . 42
7.5.7. Reliable Data Transfer (Message) . . . . . . . . . . 42 7.5.7. Reliable Data Transfer (Message) . . . . . . . . . . 42
7.5.8. Message Capacity Profile Override . . . . . . . . . . 43 7.5.8. Message Capacity Profile Override . . . . . . . . . . 42
7.5.9. No Fragmentation . . . . . . . . . . . . . . . . . . 43 7.5.9. No Fragmentation . . . . . . . . . . . . . . . . . . 43
7.6. Partial Sends . . . . . . . . . . . . . . . . . . . . . . 43 7.6. Partial Sends . . . . . . . . . . . . . . . . . . . . . . 43
7.7. Batching Sends . . . . . . . . . . . . . . . . . . . . . 44 7.7. Batching Sends . . . . . . . . . . . . . . . . . . . . . 44
7.8. Send on Active Open: InitiateWithSend . . . . . . . . . . 44 7.8. Send on Active Open: InitiateWithSend . . . . . . . . . . 44
8. Receiving Data . . . . . . . . . . . . . . . . . . . . . . . 45 8. Receiving Data . . . . . . . . . . . . . . . . . . . . . . . 44
8.1. Enqueuing Receives . . . . . . . . . . . . . . . . . . . 45 8.1. Enqueuing Receives . . . . . . . . . . . . . . . . . . . 45
8.2. Receive Events . . . . . . . . . . . . . . . . . . . . . 46 8.2. Receive Events . . . . . . . . . . . . . . . . . . . . . 46
8.2.1. Received . . . . . . . . . . . . . . . . . . . . . . 46 8.2.1. Received . . . . . . . . . . . . . . . . . . . . . . 46
8.2.2. ReceivedPartial . . . . . . . . . . . . . . . . . . . 46 8.2.2. ReceivedPartial . . . . . . . . . . . . . . . . . . . 46
8.2.3. ReceiveError . . . . . . . . . . . . . . . . . . . . 47 8.2.3. ReceiveError . . . . . . . . . . . . . . . . . . . . 47
8.3. Receive Message Properties . . . . . . . . . . . . . . . 48 8.3. Receive Message Properties . . . . . . . . . . . . . . . 47
8.3.1. UDP(-Lite)-specific Property: ECN . . . . . . . . . . 48 8.3.1. UDP(-Lite)-specific Property: ECN . . . . . . . . . . 47
8.3.2. Early Data . . . . . . . . . . . . . . . . . . . . . 48 8.3.2. Early Data . . . . . . . . . . . . . . . . . . . . . 48
8.3.3. Receiving Final Messages . . . . . . . . . . . . . . 48 8.3.3. Receiving Final Messages . . . . . . . . . . . . . . 48
9. Message Framers . . . . . . . . . . . . . . . . . . . . . . . 48
9. Message Framers . . . . . . . . . . . . . . . . . . . . . . . 49 9.1. Adding Message Framers to Connections . . . . . . . . . . 50
9.1. Adding Message Framers to Connections . . . . . . . . . . 49
9.2. Framing Meta-Data . . . . . . . . . . . . . . . . . . . . 50 9.2. Framing Meta-Data . . . . . . . . . . . . . . . . . . . . 50
10. Managing Connections . . . . . . . . . . . . . . . . . . . . 50 10. Managing Connections . . . . . . . . . . . . . . . . . . . . 50
10.1. Generic Connection Properties . . . . . . . . . . . . . 52 10.1. Generic Connection Properties . . . . . . . . . . . . . 52
10.1.1. Retransmission Threshold Before Excessive 10.1.1. Retransmission Threshold Before Excessive
Retransmission Notification . . . . . . . . . . . . . 52 Retransmission Notification . . . . . . . . . . . . 52
10.1.2. Required Minimum Corruption Protection Coverage for 10.1.2. Required Minimum Corruption Protection Coverage for
Receiving . . . . . . . . . . . . . . . . . . . . . . 52 Receiving . . . . . . . . . . . . . . . . . . . . . 52
10.1.3. Priority (Connection) . . . . . . . . . . . . . . . 53 10.1.3. Priority (Connection) . . . . . . . . . . . . . . . 53
10.1.4. Timeout for Aborting Connection . . . . . . . . . . 53 10.1.4. Timeout for Aborting Connection . . . . . . . . . . 53
10.1.5. Connection Group Transmission Scheduler . . . . . . 53 10.1.5. Connection Group Transmission Scheduler . . . . . . 53
10.1.6. Capacity Profile . . . . . . . . . . . . . . . . . . 54 10.1.6. Capacity Profile . . . . . . . . . . . . . . . . . . 54
10.1.7. Policy for using Multi-Path Transports . . . . . . . 55 10.1.7. Policy for using Multi-Path Transports . . . . . . . 55
10.1.8. Bounds on Send or Receive Rate . . . . . . . . . . . 56 10.1.8. Bounds on Send or Receive Rate . . . . . . . . . . . 56
10.1.9. Read-only Connection Properties . . . . . . . . . . 56 10.1.9. Read-only Connection Properties . . . . . . . . . . 56
10.2. TCP-specific Properties: User Timeout Option (UTO) . . . 57 10.2. TCP-specific Properties: User Timeout Option (UTO) . . . 57
10.2.1. Advertised User Timeout . . . . . . . . . . . . . . 57 10.2.1. Advertised User Timeout . . . . . . . . . . . . . . 58
10.2.2. User Timeout Enabled . . . . . . . . . . . . . . . . 58 10.2.2. User Timeout Enabled . . . . . . . . . . . . . . . . 58
10.2.3. Timeout Changeable . . . . . . . . . . . . . . . . . 58 10.2.3. Timeout Changeable . . . . . . . . . . . . . . . . . 58
10.3. Connection Lifecycle Events . . . . . . . . . . . . . . 58 10.3. Connection Lifecycle Events . . . . . . . . . . . . . . 58
10.3.1. Soft Errors . . . . . . . . . . . . . . . . . . . . 58 10.3.1. Soft Errors . . . . . . . . . . . . . . . . . . . . 59
10.3.2. Excessive retransmissions . . . . . . . . . . . . . 59 10.3.2. Excessive retransmissions . . . . . . . . . . . . . 59
11. Connection Termination . . . . . . . . . . . . . . . . . . . 59 11. Connection Termination . . . . . . . . . . . . . . . . . . . 59
12. Connection State and Ordering of Operations and Events . . . 59 12. Connection State and Ordering of Operations and Events . . . 60
13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 61 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 61
14. Security Considerations . . . . . . . . . . . . . . . . . . . 61 14. Security Considerations . . . . . . . . . . . . . . . . . . . 61
15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 62 15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 62
16. References . . . . . . . . . . . . . . . . . . . . . . . . . 63 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 63
16.1. Normative References . . . . . . . . . . . . . . . . . . 63 16.1. Normative References . . . . . . . . . . . . . . . . . . 63
16.2. Informative References . . . . . . . . . . . . . . . . . 63 16.2. Informative References . . . . . . . . . . . . . . . . . 64
Appendix A. Convenience Functions . . . . . . . . . . . . . . . 66 Appendix A. Convenience Functions . . . . . . . . . . . . . . . 66
A.1. Adding Preference Properties . . . . . . . . . . . . . . 66 A.1. Adding Preference Properties . . . . . . . . . . . . . . 66
A.2. Transport Property Profiles . . . . . . . . . . . . . . . 67 A.2. Transport Property Profiles . . . . . . . . . . . . . . . 67
A.2.1. reliable-inorder-stream . . . . . . . . . . . . . . . 67 A.2.1. reliable-inorder-stream . . . . . . . . . . . . . . . 67
A.2.2. reliable-message . . . . . . . . . . . . . . . . . . 67 A.2.2. reliable-message . . . . . . . . . . . . . . . . . . 67
A.2.3. unreliable-datagram . . . . . . . . . . . . . . . . . 68 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 . . . . . . . . . . . . . . . . . . . . . 69 Services for End Systems . . . . . . . . . . . . . . 68
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 72 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
skipping to change at page 5, line 48 skipping to change at page 5, line 39
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:
* An Action creates an Object: o An Action creates an Object:
Object := Action() Object := Action()
* An Action creates an array of Objects: o An Action creates an array of Objects:
[]Object := Action() []Object := Action()
* An Action is performed on an Object: o An Action is performed on an Object:
Object.Action() Object.Action()
* An Object sends an Event: o An Object sends an Event:
Object -> Event<> Object -> Event<>
* An Action takes a set of Parameters; an Event contains a set of o 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
skipping to change at page 7, line 12 skipping to change at page 6, line 47
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:
* A single interface to a variety of transport protocols to be used o A single interface to a variety of transport protocols to be used
in a variety of application design patterns, independent of the in a variety of application design patterns, independent of the
properties of the application and the Protocol Stacks that will be properties of the application and the Protocol Stacks that will be
used at runtime, such that all common specialized features of used at runtime, such that all common specialized features of
these protocol stacks are made available to the application as these protocol stacks are made available to the application as
necessary in a transport-independent way, to enable applications necessary in a transport-independent way, to enable applications
written to a single API to make use of transport protocols in written to a single API to make use of transport protocols in
terms of the features they provide; terms of the features they provide;
* Message-orientation, as opposed to stream-orientation, using o 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;
* Asynchronous Connection establishment, transmission, and o 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;
* Explicit support for security properties as first-order transport o 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
* Explicit support for multistreaming and multipath transport o 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].
skipping to change at page 8, line 10 skipping to change at page 7, line 45
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
skipping to change at page 8, line 34 skipping to change at page 8, line 21
the details of application interaction with Objects through Actions the details of application interaction with Objects through Actions
and Events in each phase of a Connection, following the phases (Pre- and Events in each phase of a Connection, following the phases (Pre-
Establishment, Establishment, Data Transfer, and Termination) Establishment, Establishment, Data Transfer, and Termination)
described in Section 4.1 of [I-D.ietf-taps-arch]. 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:
* Act as a server, by listening for incoming connections, receiving o 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.
* Act as a client, by connecting to a remote endpoint using o 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.
* Act as a peer, by connecting to a remote endpoint using Rendezvous o 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 endpoints that provides Reliable Data Transfer,
Preservation of data ordering, and Preservation of Message Preservation of data ordering, and Preservation of Message
Boundaries. In this case, the application can choose to receive only Boundaries. In this case, the application can choose to receive only
complete messages. complete messages.
If none of the available transport protocols provides Preservation of If none of the available transport protocols provides Preservation of
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 The behavior of the Message Properties. Selection Properties (see Section 5.2) can only
selected protocol stack(s) when sending Messages is controlled by be set during pre-establishment. They are only used to specify which
Message Properties (see Section 5.2) can only be set during pre- paths and protocol stacks can be used and are preferred by the
establishment. They are only used to specify which paths and application. Connection Properties (see Section 10.1) can also be
protocol stacks can be used and are preferred by the application. set during pre-establishment but may be changed later. They are used
Connection Properties (see Section 10.1) can also be set during pre- to inform decisions made during establishment and to fine-tune the
establishment but may be changed later. They are used to inform established connection.
decisions made during establishment and to fine-tune the established The behavior of the selected protocol stack(s) when sending Messages
connection.Section 7.5). is controlled by Message Properties (see Section 7.5).
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 in earlier stages and querying them in later stages:
* Connection Properties can be set on Preconnections o Connection Properties can be set on Preconnections
* Message Properties can be set on Preconnections, Connections and o Message Properties can be set on Preconnections, Connections and
Messages Messages
* The effect of Selection Properties can be queried on Connections o 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:
* Allowing different components of a TAPS implementation to pass o 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.
* Making code of different TAPS implementations look similar. While o Making code of different TAPS implementations look similar. While
individual programming languages may preclude strict adherence to individual programming languages may preclude strict adherence to
the aforementioned naming convention (for instance, by prohibiting the aforementioned naming convention (for instance, by prohibiting
the use of hyphens in symbols), users interacting with multiple the use of hyphens in symbols), users interacting with multiple
implementations will still benefit from the consistency resulting implementations will still benefit from the consistency resulting
from the use of visually similar symbols. 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>.
* The Namespace component MUST be empty for well-known, generic o 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.
* Protocol Specific Properties MUST use the protocol acronym as o Protocol Specific Properties MUST use the protocol acronym as
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.
* Vendor or implementation specific properties MUST use a string o Vendor or implementation specific properties MUST use a string
identifying the vendor or implementation as Namespace. identifying the vendor or implementation as 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:
* Boolean: can take the values "true" and "false"; representation is o Boolean: can take the values "true" and "false"; representation is
implementation-dependent. implementation-dependent.
* Integer: can take positive or negative numeric integer values; o Integer: can take positive or negative numeric integer values;
range and representation is implementation-dependent. range and representation is implementation-dependent.
* Numeric: can take positive or negative numeric values; range and o Numeric: can take positive or negative numeric values; range and
representation is implementation-dependent. representation is implementation-dependent.
* Enumeration: can take one value of a finite set of values, o 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; however, implementations MUST provide a
method for the application to determine the entire set of possible method for the application to determine the entire set of possible
values for each property. values for each property.
* Preference: can take one of five values (Prohibit, Avoid, Ignore, o 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.
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
skipping to change at page 14, line 32 skipping to change at page 14, line 28
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 these platforms reduces the effort for programmers
who learn the transport services interface to then apply their who learn the transport services interface to then apply their
knowledge across multiple platforms. knowledge across multiple platforms.
We therefore make the following recommendations: We therefore make the following recommendations:
* Actions, Events, and Errors in implementations of this interface o 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.
* Implementations of this interface SHOULD implement each Selection o 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 this will always result in no operation, e.g. there is
no action when the API specifies a Property that is not available no action when the API specifies a Property that is not available
in a transport protocol implemented on a specific platform. For in a transport protocol implemented on a specific platform. For
example, if TCP is the only underlying transport protocol, the example, if TCP is the only underlying transport protocol, the
Message Property "msgOrdered" can be implemented even if disabling Message Property "msgOrdered" can be implemented even if disabling
ordering will not have any effect TCP because the API does not ordering will not have any effect TCP because the API does not
guarantee out-of-order delivery. Similarly, the "msg-lifetime" guarantee out-of-order delivery. Similarly, the "msg-lifetime"
Message Property can be implemented but ignored, as the 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".
* Implementations may use other representations for Transport o 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 they are about to make, or to query the API about
potential Connections they could make. potential Connections they could make.
skipping to change at page 18, line 25 skipping to change at page 18, line 25
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 | | Require | Select only protocols/paths providing the property, |
| | the property, fail otherwise | | | fail otherwise |
+------------+----------------------------------------+ | | |
| Prefer | Prefer protocols/paths providing the | | Prefer | Prefer protocols/paths providing the property, |
| | property, proceed otherwise | | | proceed otherwise |
+------------+----------------------------------------+ | | |
| Ignore | No preference | | Ignore | No preference |
+------------+----------------------------------------+ | | |
| Avoid | Prefer protocols/paths not providing | | Avoid | Prefer protocols/paths not providing the property, |
| | the property, proceed otherwise | | | proceed otherwise |
+------------+----------------------------------------+ | | |
| Prohibit | Select only protocols/paths not | | Prohibit | Select only protocols/paths not providing the |
| | providing the property, fail otherwise | | | property, fail otherwise |
+------------+----------------------------------------+ +------------+------------------------------------------------------+
Table 1
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 queuing 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
application requirements as expressed using Require and Prohibit. application requirements as expressed using Require and Prohibit.
While preferences expressed using Prefer and Avoid influence protocol While preferences expressed using Prefer and Avoid influence protocol
and path selection as well, outcomes may vary given the same and path selection as well, outcomes may vary given the same
skipping to change at page 28, line 42 skipping to change at page 28, line 34
[I-D.ietf-taps-transport-security], many transport security protocols [I-D.ietf-taps-transport-security], many transport security protocols
require specific security parameters and constraints from the client require specific security parameters and constraints from the client
at the time of configuration and actively during a handshake. These at the time of configuration and actively during a handshake. These
configuration parameters need to be specified in the pre-connection configuration parameters need to be 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:
* Local identity and private keys: Used to perform private key o 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.Add('identity', identity)
SecurityParameters.Add('keypair', privateKey, publicKey) SecurityParameters.Add('keypair', privateKey, publicKey)
* Supported algorithms: Used to restrict what parameters are used by
o 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.
SecurityParameters.Add('supported-group', 'secp256k1') SecurityParameters.Add('supported-group', 'secp256k1')
SecurityParameters.Add('ciphersuite, 'TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256') SecurityParameters.Add('ciphersuite, 'TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256')
SecurityParameters.Add('signature-algorithm', 'ed25519') SecurityParameters.Add('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.Add('pre-shared-key', key, identity)
* Session cache management: Used to tune cache capacity, lifetime, o Session cache management: Used to tune cache capacity, lifetime,
re-use, and eviction policies, e.g., LRU or FIFO.may also me re-use, and eviction policies, e.g., LRU or FIFO.may also me
changed, but are implementation-specific. changed, but are implementation-specific.
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:
* Trust verification callback: Invoked when a Remote Endpoint's o 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)
* Identity challenge callback: Invoked when a private key operation o 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
skipping to change at page 32, line 30 skipping to change at page 32, line 16
SetNewConnectionLimit(). This mechanism allows a server to protect SetNewConnectionLimit(). This mechanism allows a server to protect
itself from being drained of resources. Each time a new Connection itself from being drained of resources. Each time a new Connection
is delivered by the ConnectionReceived Event, the value is is delivered by the ConnectionReceived Event, the value is
automatically decremented. Once the value reaches zero, no further automatically decremented. Once the value reaches zero, no further
Connections will be delivered until the caller sets the limit to a Connections will be delivered until the caller sets the limit to a
higher value. By default, this value is Infinite. The caller is higher value. By default, this value is Infinite. The caller is
also able to reset the value to Infinite at any point. also able to reset the value to Infinite at any point.
Listener -> EstablishmentError<reason?> Listener -> EstablishmentError<reason?>
A EstablishmentError occurs either when the Properties and Security An EstablishmentError occurs either when the Properties and Security
Parameters of the Preconnection cannot be fulfilled for listening or Parameters of the Preconnection cannot be fulfilled for listening or
cannot be reconciled with the Local Endpoint (and/or Remote Endpoint, cannot be reconciled with the Local Endpoint (and/or Remote Endpoint,
if specified), when the Local Endpoint (or Remote Endpoint, if if specified), when the Local Endpoint (or Remote Endpoint, if
specified) cannot be resolved, or when the application is prohibited specified) cannot be resolved, or when the application is prohibited
from listening by policy. from listening by policy.
Listener -> Stopped<> Listener -> Stopped<>
A Stopped Event occurs after the Listener has stopped listening. A Stopped Event occurs after the Listener has stopped listening.
skipping to change at page 34, line 23 skipping to change at page 34, line 10
Connection. These connections are "entangled" with each other, and Connection. These connections are "entangled" with each other, and
become part of a Connection Group. Calling Clone on any of these two become part of a Connection Group. Calling Clone on any of these two
Connections adds a third Connection to the Connection Group, and so Connections adds a third Connection to the Connection Group, and so
on. Connections in a Connection Group generally share Connection on. Connections in a Connection Group generally share Connection
Properties. However, there may be exceptions, such as "Priority Properties. However, there may be exceptions, such as "Priority
(Connection)", see Section 10.1.3. Like all other Properties, (Connection)", see Section 10.1.3. Like all other Properties,
Priority is copied to the new Connection when calling Clone(), but it Priority is copied to the new Connection when calling Clone(), but it
is not entangled: Changing Priority on one Connection does not change is not entangled: Changing Priority on one Connection does not change
it on the other Connections in the same Connection Group. it on the other Connections in the same Connection Group.
In addition, incoming entangled Connections can be received by It is also possible to check which Connections belong to the same
creating a Listener on an existing connection: Connection Group. Calling GroupedConnections() on a specific
Connection returns a set of all Connections in the same group.
Listener := Connection.ListenClone() []Connection := Connection.GroupedConnections()
ListenClone() creates a Listener that listens on the same Connections will be in the same group if the application previously
LocalEndpoint as the one the cloned Connection is using. Any new called Clone. Passive Connections can also be added to the same
Connection received by this Listener will be entangled with the group - e.g., when a Listener receives a new Connection that is just
cloned Connection. Changing one of the Connection Properties on one a new stream of an already active multi-streaming protocol instance.
Connection in the group changes it for all others. Message
Properties, however, are not entangled. For example, changing Changing one of the Connection Properties on one Connection in the
"Timeout for aborting Connection" (see Section 10.1.4) on one group changes it for all others. Message Properties, however, are
Connection in a group will automatically change this Connection not entangled. For example, changing "Timeout for aborting
Property for all Connections in the group in the same way. However, Connection" (see Section 10.1.4) on one Connection in a group will
changing "Lifetime" (see Section 7.5.1) of a Message will only affect automatically change this Connection Property for all Connections in
a single Message on a single Connection, entangled or not. the group in the same way. However, changing "Lifetime" (see
Section 7.5.1) of a Message will only affect a single Message on a
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() may 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
skipping to change at page 47, line 20 skipping to change at page 47, line 5
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 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:
* the underlying Protocol Stack supports message boundary o 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;
* the underlying Protocol Stack does not support message boundary o the underlying Protocol Stack does not support message boundary
preservation, and the Message Framer (see Section 9) cannot preservation, and the Message Framer (see Section 9) 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
* the underlying Protocol Stack does not support message boundary o 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.2.3. ReceiveError 8.2.3. ReceiveError
Connection -> ReceiveError<messageContext, reason?> Connection -> ReceiveError<messageContext, reason?>
skipping to change at page 49, line 28 skipping to change at page 49, line 11
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 facility is
designed based on the fact that many of the current application designed based on the fact that many of the current application
protocols evolved over TCP, which does not provide message boundary protocols 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
object. Then, the Message Framer can intercept all calls to Send()
or Receive() on a Connection to add Message semantics, in addition to
interacting with the setup and teardown of the Connection. A Framer
can start sending data before the application sends data if the
framing protocol requires a prefix or handshake (see [RFC8229] for an
example of such a framing protocol).
Initiate() Send() Receive() Close()
| | ^ |
| | | |
+----v----------v---------+----------v-----+
| Connection |
+----+----------+---------^----------+-----+
| | | |
| +-----------------+ |
| | Messages | |
| +-----------------+ |
| | | |
+----v----------v---------+----------v-----+
| Framer(s) |
+----+----------+---------^----------+-----+
| | | |
| +-----------------+ |
| | Byte-stream | |
| +-----------------+ |
| | | |
+----v----------v---------+----------v-----+
| Transport Protocol Stack |
+------------------------------------------+
Note that while Message Framers add the most value when placed 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].
skipping to change at page 51, line 23 skipping to change at page 51, line 33
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:
* The connection state, which can be one of the following: o The connection state, which can be one of the following:
Establishing, Established, Closing, or Closed. Establishing, Established, Closing, or Closed.
* Whether the connection can be used to send data. A connection can o 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 7.5.5. sent over this connection, see Section 7.5.5.
* Whether the connection can be used to receive data. A connection o Whether the connection can be used to receive data. A connection
can not be used for reading if the connection was created with the can not 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. The latter is only supported by received, see Section 8.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.
* For Connections that are Establishing: Transport Properties that o 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.
* For Connections that are Established, Closing, or Closed: o For Connections that are Established, Closing, or Closed:
Selection (Section 5.2) and Connection Properties (Section 10.1) Selection (Section 5.2) and Connection Properties (Section 10.1)
of the actual protocols that were selected and instantiated. of 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. Note that the actually
instantiated protocol stack may not match all Protocol Selection instantiated protocol stack may not match all Protocol Selection
Properties that the application specified on the Preconnection. Properties that the application specified on the Preconnection.
For example, a certain Protocol Selection Property that an For example, a certain Protocol Selection Property that an
application specified as Preferred may not actually be present in application specified as Preferred may not actually be present in
the chosen protocol stack because none of the currently available the chosen protocol stack because none of the currently available
transport protocols had this feature. transport protocols had this feature.
* For Connections that are Established, additional properties of the o 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.
10.1. Generic Connection Properties 10.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 Note that many Connection Properties have a corresponding Selection
skipping to change at page 56, line 5 skipping to change at page 56, line 5
This property specifies the local policy of transferring data across This property specifies the local policy of 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 not set to Disabled (see Section 5.2.13). Possible values are:
Handover: The connection should only attempt to migrate between Handover: The connection should only 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 actual thresholds to declare a path unusable are
implementation specific. implementation specific.
Interactive: The connection should attempt to use multiple paths in Interactive: The connection should attempt to minimize the latency
parallel in order to minimize loss and delay. The actual strategy for interactive traffic patterns by transmitting data across
is implementation specific. multiple paths when it is beneficial to do so. The goal of
minimizing the latency will be balanced against the cost of each
of these paths, meaning that depending on the cost of the lower-
latency path, the scheduling might choose to use a higher-latency
path. Traffic can be scheduled such that data may be transmitted
on multiple paths in parallel to achieve the lowest latency
possible. The specific scheduling algorithm is implementation-
specific.
Aggregate: The connection should attempt to use multiple paths in Aggregate: The connection should attempt to use multiple paths in
parallel in order to maximize bandwidth and possibly overcome parallel in order to maximize bandwidth and possibly overcome
bandwidth limitations of the individual paths. The actual bandwidth limitations of the individual paths. The actual
strategy is implementation specific. strategy is implementation specific.
Note that this is a local choice - the peer endpoint can choose a Note that this is a local choice - the peer endpoint can choose a
different policy. different policy.
10.1.8. Bounds on Send or Receive Rate 10.1.8. Bounds on Send or Receive Rate
skipping to change at page 60, line 5 skipping to change at page 60, line 15
12. Connection State and Ordering of Operations and Events 12. Connection State and Ordering of Operations and Events
As this interface is designed to be independent of an As this interface is designed to be independent of an
implementation's concurrency model, the details of how exactly implementation's concurrency model, the details of how exactly
actions are handled, and how events are dispatched, are actions are handled, 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:
* Ready<> occurs when a Connection created with Initiate() or o Ready<> occurs when a Connection created with Initiate() or
InitiateWithSend() transitions to Established state. InitiateWithSend() transitions to Established state.
* ConnectionReceived<> occurs when a Connection created with o ConnectionReceived<> occurs when a Connection created with
Listen() transitions to Established state. Listen() transitions to Established state.
* RendezvousDone<> occurs when a Connection created with o RendezvousDone<> occurs when a Connection created with
Rendezvous() transitions to Established state. Rendezvous() transitions to Established state.
* Closed<> occurs when a Connection transitions to Closed state o Closed<> occurs when a Connection transitions to Closed state
without error. without error.
* InitiateError<> occurs when a Connection created with Initiate() o 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.
* ConnectionError<> occurs when a Connection transitions to Closed o 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 1: 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:
* Sent<> events will occur on a Connection in the order in which the o 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).
* Received<> will never occur on a Connection before it is o 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.
* No events will occur on a Connection after it is Closed; i.e., o 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<> on
that connection. To ensure this ordering, Closed<> will not occur that connection. To ensure this ordering, Closed<> will not occur
on a Connection while other events on the Connection are still on a Connection while other events on the Connection are still
locally outstanding (i.e., known to the interface and waiting to locally outstanding (i.e., known to the interface and waiting to
be dealt with by the application). ConnectionError<> may occur be dealt with by the application). ConnectionError<> may occur
after Closed<>, but the interface must gracefully handle all cases after Closed<>, but the interface must gracefully handle all cases
where application ignores these errors. where application ignores these errors.
13. IANA Considerations 13. IANA Considerations
skipping to change at page 63, line 23 skipping to change at page 63, line 30
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.
16. References 16. References
16.1. Normative References 16.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", Work in Progress, Internet-Draft, Transport Services", draft-ietf-taps-arch-08 (work in
draft-ietf-taps-arch-07, 9 March 2020, progress), July 2020.
<http://www.ietf.org/internet-drafts/draft-ietf-taps-arch-
07.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>.
[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>.
skipping to change at page 64, line 8 skipping to change at page 64, line 14
[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>.
16.2. Informative References 16.2. Informative References
[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", Work in "Implementing Interfaces to Transport Services", draft-
Progress, Internet-Draft, draft-ietf-taps-impl-06, 9 March ietf-taps-impl-07 (work in progress), July 2020.
2020, <http://www.ietf.org/internet-drafts/draft-ietf-
taps-impl-06.txt>.
[I-D.ietf-taps-minset] [I-D.ietf-taps-minset]
Welzl, M. and S. Gjessing, "A Minimal Set of Transport Welzl, M. and S. Gjessing, "A Minimal Set of Transport
Services for End Systems", Work in Progress, Internet- Services for End Systems", draft-ietf-taps-minset-11 (work
Draft, draft-ietf-taps-minset-11, 27 September 2018, in progress), September 2018.
<http://www.ietf.org/internet-drafts/draft-ietf-taps-
minset-11.txt>.
[I-D.ietf-taps-transport-security] [I-D.ietf-taps-transport-security]
Enghardt, T., Pauly, T., Perkins, C., Rose, K., and C. Enghardt, T., Pauly, T., Perkins, C., Rose, K., and C.
Wood, "A Survey of the Interaction Between Security Wood, "A Survey of the Interaction Between Security
Protocols and Transport Services", Work in Progress, Protocols and Transport Services", draft-ietf-taps-
Internet-Draft, draft-ietf-taps-transport-security-12, 23 transport-security-12 (work in progress), April 2020.
April 2020, <http://www.ietf.org/internet-drafts/draft-
ietf-taps-transport-security-12.txt>.
[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", Work in Progress, Internet-Draft, Datagram Transports", draft-ietf-tsvwg-datagram-plpmtud-22
draft-ietf-tsvwg-datagram-plpmtud-22, 10 June 2020, (work in progress), 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, [RFC2914] Floyd, S., "Congestion Control Principles", BCP 41,
RFC 2914, DOI 10.17487/RFC2914, September 2000, RFC 2914, DOI 10.17487/RFC2914, September 2000,
<https://www.rfc-editor.org/info/rfc2914>. <https://www.rfc-editor.org/info/rfc2914>.
[RFC3246] Davie, B., Charny, A., Bennet, J.C.R., Benson, K., Le [RFC3246] Davie, B., Charny, A., Bennet, J., Benson, K., Le Boudec,
Boudec, J.Y., Courtney, W., Davari, S., Firoiu, V., and D. 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 66, line 15 skipping to change at page 66, line 15
[RFC8084] Fairhurst, G., "Network Transport Circuit Breakers", [RFC8084] Fairhurst, G., "Network Transport Circuit Breakers",
BCP 208, RFC 8084, DOI 10.17487/RFC8084, March 2017, BCP 208, RFC 8084, DOI 10.17487/RFC8084, March 2017,
<https://www.rfc-editor.org/info/rfc8084>. <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
of IKE and IPsec Packets", RFC 8229, DOI 10.17487/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>.
[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>.
skipping to change at page 66, line 36 skipping to change at page 66, line 40
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>.
[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) , 15 April Internet Symposium (GI) workshop (GI 2018) , April 2018.
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 added to 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.Add(some_property, avoid)" is equivalent to
"TransportProperties.Avoid(some_property)": "TransportProperties.Avoid(some_property)":
skipping to change at page 67, line 26 skipping to change at page 67, line 26
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. An example of a protocol that provides this
service is TCP. It should consist of the following properties: service is TCP. 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. An example of a protocol
that provides this service is SCTP. It should consist of the that provides this service is SCTP. 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 should
consist of the following properties: consist 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 the Capacity Profile Property,
see Section 10.1.6 accordingly and my benefit from controlling see Section 10.1.6 accordingly and my 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 [I-D.ietf-taps-minset] identifies a minimal set of transport services
that end systems should offer. These services make all non-security- that end systems should offer. These services make all non-security-
skipping to change at page 69, line 22 skipping to change at page 69, line 10
and 2) do not get in the way of a possible implementation over TCP and 2) do not get in the way of a possible implementation over TCP
(or, with limitations, UDP). The following text explains how this (or, with limitations, UDP). The following text explains how this
minimal set is reflected in the present API. For brevity, it is minimal set is reflected in the present API. For brevity, it is
based on the list in Section 4.1 of [I-D.ietf-taps-minset], updated based on the list in Section 4.1 of [I-D.ietf-taps-minset], updated
according to the discussion in Section 5 of [I-D.ietf-taps-minset]. according to the discussion in Section 5 of [I-D.ietf-taps-minset].
This list is a subset of the transport features in Appendix A of This list is a subset of the transport features in Appendix A of
[I-D.ietf-taps-minset], which refers to the primitives in "pass 2" [I-D.ietf-taps-minset], which refers to the primitives in "pass 2"
(Section 4) of [RFC8303] for further details on the implementation (Section 4) of [RFC8303] for further details on the implementation
with TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT. with TCP, MPTCP, UDP, UDP-Lite, SCTP and LEDBAT.
* Connect: "Initiate" Action (Section 6.1). o Connect: "Initiate" Action (Section 6.1).
* Listen: "Listen" Action (Section 6.2). o Listen: "Listen" Action (Section 6.2).
* Specify number of attempts and/or timeout for the first o 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 7.8). (Section 6.1) or "InitiateWithSend" Action (Section 7.8).
* Disable MPTCP: "Parallel Use of Multiple Paths" Property o Disable MPTCP: "Parallel Use of Multiple Paths" Property
(Section 5.2.13). (Section 5.2.13).
* Hand over a message to reliably transfer (possibly multiple times) o Hand over a message to reliably transfer (possibly multiple times)
before connection establishment: "InitiateWithSend" Action before connection establishment: "InitiateWithSend" Action
(Section 7.8). (Section 7.8).
* Change timeout for aborting connection (using retransmit limit or o 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 10.1.4). time value (Section 10.1.4).
* Timeout event when data could not be delivered for too long: o Timeout event when data could not be delivered for too long:
"ConnectionError" Event (Section 11). "ConnectionError" Event (Section 11).
* Suggest timeout to the peer: "TCP-specific Property: User Timeout" o Suggest timeout to the peer: "TCP-specific Property: User Timeout"
(Section 10.2). (Section 10.2).
* Notification of Excessive Retransmissions (early warning below o Notification of Excessive Retransmissions (early warning below
abortion threshold): "Notification of excessive retransmissions" abortion threshold): "Notification of excessive retransmissions"
property (Section 5.2.16). property (Section 5.2.16).
* Notification of ICMP error message arrival: "Notification of ICMP 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).
* Choose a scheduler to operate between streams of an association: o Choose a scheduler to operate between streams of an association:
"Connection Group Transmission Scheduler" property "Connection Group Transmission Scheduler" property
(Section 10.1.5). (Section 10.1.5).
* Configure priority or weight for a scheduler: "Priority o Configure priority or weight for a scheduler: "Priority
(Connection)" property (Section 10.1.3). (Connection)" property (Section 10.1.3).
* "Specify checksum coverage used by the sender" and "Disable o "Specify checksum coverage used by the sender" and "Disable
checksum when sending": "Corruption Protection Length" property checksum when sending": "Corruption Protection Length" property
(Section 7.5.6) and "Full Checksum Coverage on Sending" property (Section 7.5.6) and "Full Checksum Coverage on Sending" property
(Section 5.2.7). (Section 5.2.7).
* "Specify minimum checksum coverage required by receiver" and o "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 10.1.2) and "Full Checksum Coverage on Receiving" (Section 10.1.2) and "Full Checksum Coverage on Receiving"
property (Section 5.2.8). property (Section 5.2.8).
* "Specify DF" field and "Request not to bundle messages": the "No o "Specify DF" field and "Request not to bundle messages": the "No
Fragmentation" Message Property combines both of these requests, Fragmentation" Message Property combines both of these requests,
i.e. if a request not to bundle messages is made, this also turns 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 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 allows this (only UDP and UDP-Lite, which cannot bundle messages
anyway) (Section 7.5.9). anyway) (Section 7.5.9).
* Get max. transport-message size that may be sent using a non- o 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 10.1.9.2). (Section 10.1.9.2).
* Get max. transport-message size that may be received from the o 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 10.1.9.4). (Section 10.1.9.4).
* Obtain ECN field: "ECN" is a defined UDP(-Lite)-specific read-only o Obtain ECN field: "ECN" is a defined UDP(-Lite)-specific read-only
Message Property of the MessageContext object (Section 8.3.1). Message Property of the MessageContext object (Section 8.3.1).
* "Specify DSCP field", "Disable Nagle algorithm", "Enable and o "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 [I-D.ietf-taps-minset], these transport features
are collectively offered via the "Capacity Profile" property are collectively offered via the "Capacity Profile" property
(Section 10.1.6). Per-Message control is offered via the "Message (Section 10.1.6). Per-Message control is offered via the "Message
Capacity Profile Override" property (Section 7.5.8). Capacity Profile Override" property (Section 7.5.8).
* Close after reliably delivering all remaining data, causing an o 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 [I-D.ietf-taps-minset]
(Section 11). (Section 11).
* "Abort without delivering remaining data, causing an event o "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 11). (Section 11).
* "Reliably transfer data, with congestion control", "Reliably o "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 7). Reliability is controlled via the "Reliable Data (Section 7). 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 7.5.7). Data Transfer (Message)" Message Property (Section 7.5.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 9). The choice of congestion control via Message Framers (Section 9). The choice of congestion control
is provided via the "Congestion control" property (Section 5.2.9). is provided via the "Congestion control" property (Section 5.2.9).
* Configurable Message Reliability: the "Lifetime" Message Property o 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 7.5.1). (Section 7.5.1).
* "Ordered message delivery (potentially slower than unordered)" and o "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 7.5.3). Property "Ordered" (Section 7.5.3).
* Request not to delay the acknowledgement (SACK) of a message: o 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 10.1.6) or the "Message the "Capacity Profile" Property (Section 10.1.6) or the "Message
Capacity Profile Override" Message Property (Section 7.5.8) with Capacity Profile Override" Message Property (Section 7.5.8) with
value "Low Latency/Interactive". value "Low Latency/Interactive".
* Receive data (with no message delimiting): "Received" Event o Receive data (with no message delimiting): "Received" Event
(Section 8.2.1). See Section 9 for handling Message framing in (Section 8.2.1). See Section 9 for handling Message framing in
situations where the Protocol Stack only provides a byte-stream situations where the Protocol Stack only provides a byte-stream
transport. transport.
* Receive a message: "Received" Event (Section 8.2.1), using Message o Receive a message: "Received" Event (Section 8.2.1), using Message
Framers (Section 9). Framers (Section 9).
* Information about partial message arrival: "ReceivedPartial" Event o Information about partial message arrival: "ReceivedPartial" Event
(Section 8.2.2). (Section 8.2.2).
* Notification of send failures: "Expired" Event (Section 7.3.2) and o Notification of send failures: "Expired" Event (Section 7.3.2) and
"SendError" Event (Section 7.3.3). "SendError" Event (Section 7.3.3).
* Notification that the stack has no more user data to send: o 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 7.3.1). (Section 7.3.1).
* Notification to a receiver that a partial message delivery has o Notification to a receiver that a partial message delivery has
been aborted: "ReceiveError" Event (Section 8.2.3). been aborted: "ReceiveError" Event (Section 8.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
CH- 8004 Zurich 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
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
skipping to change at page 73, line 33 skipping to change at page 73, line 23
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. 153 change blocks. 
223 lines changed or deleted 250 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/