Draft: draft-ietf-taps-impl

Commentary: Starting to address This is an early review , to check if we like the structure . I 'd also like help filling out the SCTP section ! 
 I can also help with SCTP , which I would do in the same style that I suggest above ( for TCP , in my example of " Abort " ) - also later . 
 We 've updated Implementation mapping details for most protocols with , but we did n't tackle SCTP yet . 
 I 'm fine with this being assigned to me . However , it 's more than just writing the SCTP text . Here 's the relevant part of what I wrote in PR : I do n't suggest to delete much of the text that 's there but definitely amend it with the RFC reference at least for what 's covered in RFC 8303 . There 's a very direct line from this type of text in RFC 8303 to the original specs , so I do believe that should be helpful . That 's ( obviously ) post - Montreal though ! 
 please send a PR along these lines . 
 LGTM modulo mwelzl changes . I think this is a good step forward . This said , I think we should describe things focusing on the transport 's API call to be made ( in line with the spec - that 's why we have RFCs 8303 and 8304 ) rather than protocol internals . E.g. , rather than saying that  on a TCP connection transmits a  , I think we should simply say that  calls ABORT.TCP [ RFC 8303 , Section 4.1 ] . I can take care of these things , later . I 'd still like to focus more on the API doc at this time .
Paragraph (version A):
Connection lifetime for TCP translates fairly simply into the the
abstraction presented to an application.  When the TCP three-way
handshake is complete, its layer of the Protocol Stack can be
considered Ready (established).  This event will cause racing of
Protocol Stack options to complete if TCP is the top-level protocol,
at which point the application can be notified that the Connection is
Ready to send and receive.
Paragraph (version A):
If the application sends a Close, that can translate to a graceful
termination of the TCP connection, which is performed by sending a
FIN to the remote endpoint.  If the application sends an Abort, then
the TCP state can be closed abruptly, leading to a RST being sent to
the peer.
Paragraph (version A):
Without a layer of framing (a top-level protocol in the established
Protocol Stack that preserves message boundaries, or an application-
supplied deframer) on top of TCP, the receiver side of the transport
system implementation can only treat the incoming stream of bytes as
a single Message, terminated by a FIN when the Remote Endpoint closes
the Connection.
Paragraph (version A):
UDP as a direct transport does not provide any handshake or
connectivity state, so the notion of the transport protocol becoming
Ready or established is degenerate.  Once the system has validated
that there is a route on which to send and receive UDP datagrams, the
protocol is considered Ready.  Similarly, a Close or Abort has no
meaning to the on-the-wire protocol, but simply leads to the local
state being torn down.
Paragraph (version A):
When sending and receiving messages over UDP, each Message should
correspond to a single UDP datagram.  The Message can contain
metadata about the packet, such as the ECN bits applied to the
packet.
Paragraph (version A):
The mapping of a TLS stream abstraction into the application is
equivalent to the contract provided by TCP (see tcp).  The Ready
state should be determined by the completion of the TLS handshake,
which involves potentially several more round trips beyond the TCP
handshake.  The application should not be notified that the
Connection is Ready until TLS is established.
Paragraph (version B):
Each protocol that can run as part of a Transport Services
implementation defines both its API mapping as well as implementation
details.
Paragraph (version B):
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):
Unconnected.  Unconnected protocols do not establish explicit
state between endpoints, and do not perform a handshake during
Connection establishment.
Paragraph (version B):
Connected.  Connected protocols establish state between endpoints,
and perform a handshake during Connection establishment.  The
handshake may be 0-RTT to send data or resume a session, but
bidirectional traffic is required to confirm connectedness.
Paragraph (version B):
Multiplexing Connected.  Multiplexing Connected protocols share
properties with Connected protocols, but also explictly support
opening multiple application-level flows.  This means that they
can support cloning new Connection objects without a new explicit
handshake.
Paragraph (version B):
Byte-stream.  Byte-stream protocols do not define any Message
boundaries of their own apart from the end of a stream in each
direction.
Paragraph (version B):
Datagram.  Datagram protocols define Message boundaries at the
same level of transmission, such that only complete (not partial)
Messages are supported.
Paragraph (version B):
Message.  Message protocols support Message boundaries that can be
sent and received either as complete or partial Messages.  Maximum
Message lengths can be defined, and Messages can be partially
reliable.
Paragraph (version B):
TCP connections between two hosts map directly to Connection
objects.
Paragraph (version B):
Calling "Initiate" on a TCP Connection causes it to reserve a
local port, and send a SYN to the Remote Endpoint.
Paragraph (version B):
Early idempotent data is sent on a TCP Connection in the SYN, as
TCP Fast Open data.
Paragraph (version B):
A TCP Connection is ready once the three-way handshake is
complete.
Paragraph (version B):
TCP can throw various errors during connection setup.
Specifically, it is important to handle a RST being sent by the
peer during the handshake.
Paragraph (version B):
Once established, TCP throws errors whenever the connection is
disconnected, such as due to receive a RST from the peer; or
hitting a TCP retransmission timeout.
Paragraph (version B):
Calling "Listen" for TCP binds a local port and prepares it to
receive inbound SYN packets from peers.
Paragraph (version B):
TCP Listeners will deliver new connections once they have replied
to an inbound SYN with a SYN-ACK.
Paragraph (version B):
Calling "Clone" on a TCP Connection creates a new Connection with
equivalent parameters.  The two Connections are otherwise
independent.
Paragraph (version B):
TCP does not on its own preserve Message boundaries.  Calling
"Send" on a TCP connection lays out the bytes on the TCP send
stream without any other delineation.  Any Message marked as Final
will cause TCP to send a FIN once the Message has been completely
written.
Paragraph (version B):
TCP delivers a stream of bytes without any Message delineation.
All data delivered in the "Received" or "ReceivedPartial" event
will be part of a single stream-wide Message that is marked Final
(unless a MessageFramer is used).  EndOfMessage will be delivered
when the TCP Connection has received a FIN from the peer.
Paragraph (version B):
Calling "Close" on a TCP Connection indicates that the Connection
should be gracefully closed by sending a FIN to the peer and
waiting for a FIN-ACK before delivering the "Closed" event.
Paragraph (version B):
Calling "Abort" on a TCP Connection indicates that the Connection
should be immediately closed by sending a RST to the peer.
Paragraph (version B):
UDP connections represent a pair of specific IP addresses and
ports on two hosts.
Paragraph (version B):
Calling "Initiate" on a UDP Connection causes it to reserve a
local port, but does not generate any traffic.
Paragraph (version B):
Early data on a UDP Connection does not have any special meaning.
The data is sent whenever the Connection is Ready.
Paragraph (version B):
A UDP Connection is ready once the system has reserved a local
port and has a path to send to the Remote Endpoint.
Paragraph (version B):
UDP Connections can only generate errors on initiation due to port
conflicts on the local system.
Paragraph (version B):
Once in use, UDP throws errors upon receiving ICMP notifications
indicating failures in the network.
Paragraph (version B):
Calling "Listen" for UDP binds a local port and prepares it to
receive inbound UDP datagrams from peers.
Paragraph (version B):
UDP Listeners will deliver new connections once they have received
traffic from a new Remote Endpoint.
Paragraph (version B):
Calling "Clone" on a UDP Connection creates a new Connection with
equivalent parameters.  The two Connections are otherwise
independent.
Paragraph (version B):
Calling "Send" on a UDP connection sends the data as the payload
of a complete UDP datagram.  Marking Messages as Final does not
change anything in the datagram's contents.
Paragraph (version B):
UDP only delivers complete Messages to "Received", each of which
represents a single datagram received in a UDP packet.
Paragraph (version B):
Calling "Close" on a UDP Connection releases the local port
reservation.
Paragraph (version B):
Calling "Abort" on a UDP Connection is identical to calling
"Close".
Paragraph (version B):
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 B):
Connection objects represent a single TLS connection running over
a TCP connection between two hosts.
Paragraph (version B):
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 B):
Early idempotent 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 Option can also be enabled
automatically.
Paragraph (version B):
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 B):
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 B):
TLS connections will generate TCP errors, or errors due to
failures to rekey or decrypt received messages.
Paragraph (version B):
Calling "Listen" for TLS listens on TCP, and sets up received
connections to perform server-side TLS handshakes.
Paragraph (version B):
TLS Listeners will deliver new connections once they have
successfully completed both TCP and TLS handshakes.
Paragraph (version B):
As with TCP, calling "Clone" on a TLS Connection creates a new
Connection with equivalent parameters.  The two Connections are
otherwise independent.
Paragraph (version B):
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 B):
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 B):
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 B):
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 B):
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 B):
Connection objects represent a single DTLS connection running over
a set of UDP ports between two hosts.
Paragraph (version B):
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 B):
A DTLS Connection is ready once the TLS handshake is complete and
keys have been established to encrypt application data.
Paragraph (version B):
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 B):
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 B):
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 B):
Calling "Initiate" on an HTTP connection intiates a TCP or TLS
connection as a client.
Paragraph (version B):
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 B):
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 B):
HTTP Connections deliver Messages in which HTTP header values
attached to MessageContexts, and HTTP bodies in Message data.
Paragraph (version B):
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):
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 (possibly after some
timeout), or after an individual stream Connection sends an Abort.
Paragraph (version A):
Messages over a direct QUIC stream should be represented similarly to
the TCP stream (one Message per direction, see tcp), unless a framing
mapping is used on top of QUIC.
Paragraph (version B):
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 B):
Connection objects represent a single QUIC stream on a QUIC
connection.
Paragraph (version B):
Connection objects represent a single HTTP/2 stream on a HTTP/2
connection.