Draft: draft-ietf-taps-impl

Commentary: Please merge . Completeness really is n't necessary . If this spec is used , the published RFC CAN be updated or to , at the moment , I 'd prefer to ship a spec sooner , rather than add too much , so let 's converge:- ) . 
 Brought back multicast for now . Good to merge ? 
 I think we can merge this and break out the remaining parts as separate issues as suggested by . 
 See discussion on 
 Provide a complete template that covers all functions / properties from the API . Indicate how the template should be used ( e.g. leave out the parts that are not relevant for a particular protocol or include all fields and mark fields that are not relevant as such . 
 I 'm wondering if this is really something that 's in scope that we should cover . We do have the message properties section that explains how to implement various properties , but I think adding each property to every protocol mapping will be a huge amount of text that will be difficult to get exactly right . 
 I agree , we have additional properties since we opened this issue to check the mapping and make sure we have a complete coverage . We should still be consistent in how we treat things though , and perhaps add a sentence that we do not describe all the properties for instance . I have made a pass through to check the mapping from the API to impl . draft for all the protocol mappings as a basis for making things consistent . Here is the summary . cover the same actions and events for all the protocols with the exceptions that UDP Multicast does not cover the ConnectionError event and SCTP covers the Priority connection property . And MPTCP and UDP - lite are special as they refer back to the base protocols . is one terminology inconsistency where the impl . draft refers to InitiateError and this has been generalized to EstablishmentError in the API I missed something , there are only two actions that can be made on a connection that are not covered , addRemote and removeRemote . This is probably fine as they do not mean much for most of the protocols ( or we could add them to be complete ) . We should perhaps mention how they relate to MPTCP though if we leave them out . also do not cover the Preconnection . Rendezvous action . Again this may be fine as it is a bit special ( or we can mention it for consistency . ) the events , we cover a subset with main focus on the connection related events . The Closed Event and some events related to connection setup are missing . As we cover ConnectionError we should perhaps cover the Closed event as well ? We do not cover any of the Send or Receive events which seems fine . relation to Connection and Message properties , we do not cover any of them except for the Connection priority covered for SCTP and we talk about some properties in connection to UDP - lite and MPTCP . SCTP also has support for partial reliability and unordered messages so not sure why the priority part was singled out and . any particular reasoning behind this part ? Possibly we should remove the priority part for SCTP or discuss it in running text in a similar fashion as for UDP - lite and MPTCP may want to update the UDP - lite description to also say something about what properties it supports over UDP . The current description sounds like it is a subset . Once we agree on how to deal with the bullets above , only smaller modifications should be needed to the text . 
 should be ; SCTP priority should be removed the inconsistency addRemote and removeRemote text related to MPTCP action Closed Event item 1 , no further action UDP - Lite description 
 Currently , the implementation document does not have mappings for MPTCP , even though MPTCP is part of minset . Should be boring , right ? :) 
 Should be taken care of by , yes 
 closed byPR 
 Right now , the per - protocol behavior is specified in Implementation , which is an Informational document ; however , this stuff really should be specified normatively . So either they should be split out into ( one or more ? ) separate documents , or Implementation should be made Normative just for the sake of one of its sections ( which imo would be weird ) . 
 I guess having a separate document for the per - protocol behaviour makes a lot of sense . This document than can also define names for protocol specific properties . 
 Interim discussion : considering splitting off a non - informational document for mapping definitions 
 Last discussion ended in agreement on splitting out protocol mappings . Two options were discussed 1 ) taking out all protocol mappings , 2 ) leaving TCP and UDP as the two basic protocols and moving the other mappings . Good if we can conclude on which path to take . 
 I suggest that keeping UDP and TCP in here could be a simple expedient , especially if we make it clear that other RFCs can specify additional mappings . These two are very long - established transport protocols , and I think we can rapidly conclude this spec using them . Whilst I would be very happy to also see bindings for other important transports , that seems like something that could delay the group . 
 Leave minset protocols ( UDP , TCP , SCTP , MPTCP ) , and define the template for new mappings . Split out drafts : ( TLS + DTLS ) , QUIC ( and fallback to TLS , maybe join with TLS ) , HTTP 
 Just a small correction : minset also includes UDP - Lite , and the LEDBAT congestion control ( the latter should probably be skipped since its encapsulation still is n't spec'd ) . 
 We should apply this as soon as possible as it makes the implementation consistent with minset , but deleting UDP multicast really hurts .Can we re - add the UDP multicast part , especially as this does not seem to be enough for an individual mapping document . Let 's merge and fix the rest separately .
Paragraph (version A):
Each protocol that can run as part of a Transport Services
implementation defines both its API mapping as well as implementation
details.  API mappings for a protocol apply most to Connections in
which the given protocol is the "top" of the Protocol Stack.  For
example, the mapping of the "Send" function for TCP applies to
Connections in which the application directly sends over TCP.  If
HTTP/2 is used on top of TCP, the HTTP/2 mappings take precendence.
Paragraph (version B):
Each protocol that can run as part of a Transport Services
implementation should have a well-defined API mapping.  API mappings
for a protocol apply most to Connections in which the given protocol
is the "top" of the Protocol Stack.  For example, the mapping of the
"Send" function for TCP applies to Connections in which the
application directly sends over TCP.
Paragraph (version B):
This document defines the API mappings for protocols defined in I-
D.ietf-taps-minset.  Other protocol mappings can be provided as
separate documents, following the mapping template appendix-mapping-
template.
Paragraph (version B):
API mappings for MPTCP are identical to TCP.  MPTCP adds support for
multipath properties, such as "Multi-Paths Transport" and "Policy for
using Multi-Path Transports".
Paragraph (version B):
API mappings for UDP-Lite are identical to UDP.  Properties that
require checksum coverage are not supported by UDP-Lite, such as
"Corruption Protection Length", "Full Checksum Coverage on Sending",
"Required Minimum Corruption Protection Coverage for Receiving", and
"Full Checksum Coverage on Receiving".
Paragraph (version A):
The mapping of a TLS stream abstraction into the application is
equivalent to the contract provided by TCP (see tcp), and builds upon
many of the actions of TCP connections.
Paragraph (version A):
Connection objects represent a single TLS connection running over
a TCP connection between two hosts.
Paragraph (version A):
Calling "Initiate" on a TLS Connection causes it to first initiate
a TCP connection.  Once the TCP protocol is Ready, the TLS
handshake will be performed as a client (starting by sending a
"client_hello", and so on).
Paragraph (version A):
Early safely replayable data is supported by TLS 1.3, and sends
encrypted application data in the first TLS message when
performing session resumption.  For older versions of TLS, or if a
session is not being resumed, the initial data will be delayed
until the TLS handshake is complete.  TCP Fast Open can also be
enabled automatically.
Paragraph (version A):
A TLS Connection is ready once the underlying TCP connection is
Ready, and TLS handshake is also complete and keys have been
established to encrypt application data.
Paragraph (version A):
In addition to TCP initiation errors, TLS can generate errors
during its handshake.  Examples of error include a failure of the
peer to successfully authenticate, the peer rejecting the local
authentication, or a failure to match versions or algorithms.
Paragraph (version A):
TLS connections will generate TCP errors, or errors due to
failures to rekey or decrypt received messages.
Paragraph (version A):
Calling "Listen" for TLS listens on TCP, and sets up received
connections to perform server-side TLS handshakes.
Paragraph (version A):
TLS Listeners will deliver new connections once they have
successfully completed both TCP and TLS handshakes.
Paragraph (version A):
As with TCP, calling "Clone" on a TLS Connection creates a new
Connection with equivalent parameters.  The two Connections are
otherwise independent.
Paragraph (version A):
Like TCP, TLS does not preserve message boundaries.  Although
application data is framed natively in TLS, there is not a general
guarantee that these TLS messages represent semantically
meaningful application stream boundaries.  Rather, sending data on
a TLS Connection only guarantees that the application data will be
transmitted in an encrypted form.  Marking Messages as Final
causes a "close_notify" to be generated once the data has been
written.
Paragraph (version A):
Like TCP, TLS delivers a stream of bytes without any Message
delineation.  The data is decrypted prior to being delivered to
the application.  If a "close_notify" is received, the stream-wide
Message will be delivered with EndOfMessage set.
Paragraph (version A):
Calling "Close" on a TLS Connection indicates that the Connection
should be gracefully closed by sending a "close_notify" to the
peer and waiting for a corresponding "close_notify" before
delivering the "Closed" event.
Paragraph (version A):
Calling "Abort" on a TCP Connection indicates that the Connection
should be immediately closed by sending a "close_notify",
optionally preceded by "user_canceled", to the peer.
Implementations do not need to wait to receive "close_notify"
before delivering the "Closed" event.
Paragraph (version A):
DTLS follows the same behavior as TLS (tls), with the notable
exception of not inheriting behavior directly from TCP.  Differences
from TLS are detailed below, and all cases not explicitly mentioned
should be considered the same as TLS.
Paragraph (version A):
Connection objects represent a single DTLS connection running over
a set of UDP ports between two hosts.
Paragraph (version A):
Calling "Initiate" on a DTLS Connection causes it reserve a UDP
local port, and begin sending handshake messages to the peer over
UDP.  These messages are reliable, and will be automatically
retransmitted.
Paragraph (version A):
A DTLS Connection is ready once the TLS handshake is complete and
keys have been established to encrypt application data.
Paragraph (version A):
Sending over DTLS does preserve message boundaries in the same way
that UDP datagrams do.  Marking a Message as Final does send a
"close_notify" like TLS.
Paragraph (version A):
Receiving over DTLS delivers one decrypted Message for each
received DTLS datagram.  If a "close_notify" is received, a
Message will be delivered that is marked as Final.
Paragraph (version A):
HTTP requests and responses map naturally into Messages, since they
are delineated chunks of data with metadata that can be sent over a
transport.  To that end, HTTP can be seen as the most prevalent
framing protocol that runs on top of streams like TCP, TLS, etc.
Paragraph (version A):
In order to use a transport Connection that provides HTTP Message
support, the establishment and closing of the connection can be
treated as it would without the framing protocol.  Sending and
receiving of Messages, however, changes to treat each Message as a
well-delineated HTTP request or response, with the content of the
Message representing the body, and the Headers being provided in
Message metadata.
Paragraph (version A):
Connection objects represent a flow of HTTP messages between a
client and a server, which may be an HTTP/1.1 connection over TCP,
or a single stream in an HTTP/2 connection.
Paragraph (version A):
Calling "Initiate" on an HTTP connection intiates a TCP or TLS
connection as a client.
Paragraph (version A):
Calling "Clone" on an HTTP Connection opens a new stream on an
existing HTTP/2 connection when possible.  If the underlying
version does not support multiplexed streams, calling "Clone"
simply creates a new parallel connection.
Paragraph (version A):
When an application sends an HTTP Message, it is expected to
provide HTTP header values as a MessageContext in a canonical
form, along with any associated HTTP message body as the Message
data.  The HTTP header values are encoded in the specific version
format upon sending.
Paragraph (version A):
HTTP Connections deliver Messages in which HTTP header values
attached to MessageContexts, and HTTP bodies in Message data.
Paragraph (version A):
Calling "Close" on an HTTP Connection will only close the
underlying TLS or TCP connection if the HTTP version does not
support multiplexing.  For HTTP/2, for example, closing the
connection only closes a specific stream.
Paragraph (version A):
QUIC provides a multi-streaming interface to an encrypted transport.
Each stream can be viewed as equivalent to a TLS stream over TCP, so
a natural mapping is to present each QUIC stream as an individual
Connection.  The protocol for the stream will be considered Ready
whenever the underlying QUIC connection is established to the point
that this stream's data can be sent.  For streams after the first
stream, this will likely be an immediate operation.
Paragraph (version A):
Closing a single QUIC stream, presented to the application as a
Connection, does not imply closing the underlying QUIC connection
itself.  Rather, the implementation may choose to close the QUIC
connection once all streams have been closed (often after some
timeout), or after an individual stream Connection sends an Abort.
Paragraph (version A):
Connection objects represent a single QUIC stream on a QUIC
connection.
Paragraph (version A):
Similar to QUIC (quic), HTTP/2 provides a multi-streaming interface.
This will generally use HTTP as the unit of Messages over the
streams, in which each stream can be represented as a transport
Connection.  The lifetime of streams and the HTTP/2 connection should
be managed as described for QUIC.
Paragraph (version A):
It is possible to treat each HTTP/2 stream as a raw byte-stream
instead of a carrier for HTTP messages, in which case the Messages
over the streams can be represented similarly to the TCP stream (one
Message per direction, see tcp).
Paragraph (version A):
Connection objects represent a single HTTP/2 stream on a HTTP/2
connection.