| TSVWG | G. Fairhurst |
| Internet-Draft | T. Jones |
| Intended status: Informational | University of Aberdeen |
| Expires: May 17, 2018 | A. Brunstrom |
| Karlstad University | |
| D. Ros | |
| Simula Research Laboratory | |
| November 13, 2017 |
The NEAT Interface to Transport Services
draft-fairhurst-taps-neat-01
The NEAT System provides an example of a system designed to implement the TAPS Transport Services. This document presents the transport services that the NEAT User API provides to an application or upper-layer protocol. It also describes primitives needed to interface to the NEAT Policy Manager and how policies can be adjusted to match the API behaviour to the properties required by an application or upper-layer protocol using the NEAT User API.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on May 17, 2018.
Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
The NEAT (New, Evolutive API and Transport-Layer Architecture for the Internet) [NEAT] System provides a call-back driven API to the network transport layer. It presents a set of transport services [RFC8095] that the NEAT User API provides to an application or upper-layer protocol.
The NEAT System has been implemented in the NEAT User Module. The focus of the present document is on the NEAT User API providing transport services to applications. This utilises a lower interface provided by a Kernel Programming Interface (KPI), to access the traditional Socket API or a transport service implemented in userspace.
This has been designed to support one-sided deployment, and a NEAT System can therefore exchange data with a variety of transport peers, including:
Applications that use the NEAT User API can provide information about the features desired from the transport layer and determine the properties of the offered transport service. It is this additional information that enables the NEAT System to move beyond the constraints of the traditional Socket API, since the stack then becomes aware of what the application/user actually desires or requires for each traffic flow. The additional information can be used to automatically identify which transport components (protocol and other transport mechanisms) could be used to realise the required transport service. This can drive the selection by the NEAT System of the best transport components to use and determine how these need to be configured [I-D.grinnemo-taps-he]. In making decisions, the NEAT System can utilise policy information provided at configuration, previously discovered path characteristics and probing techniques. This can be provided by a policy manager acting below the NEAT User API.
+-------------+
| Application |
+-------------+
| /\ Events & Primitives, Set/Get Properties
\/ |
-+-+-+-+-+-+ Callback-based NEAT User API
| /\
\/ |
+------------+ Properties +-----------+ +-----------+
| NEAT |----------->| Policy |<----| Policy |
| Logic |<-----------| Manager | | Info Base |
+------------+ Candidates +-----------+ +-----------+
| | |
+-----------+ +-----------+ +-----------+
| Transport | | Transport | | Path Char.|
| Protocol | | Protocol | | Info Base |
+-----------+ ... +-----------+ +-----------+
| | |
-------------------------------------------
| |
+-----------+ +-----------+
| Network | | Network |
| Interface | | Interface |
+-----------+ ... +-----------+
Figure 1: An abstract presentation of the NEAT Architecture and User API.
The architecture of the NEAT System is presented in [D1.1], and depicted in Figure 1. Some important features of NEAT compared to the existing Sockets API are:
The NEAT Library is an open source implementation and is available for download [NEAT-GIT]. This also provides tutorials and examples of code utilising the API and descriptions of the way in the which callback mechanisms can be used to build applications that use this interface. Further documentation for the current NEAT System is available at the NEAT Project web page, [NEAT-DOC].
Applications interact with the network by sending, receiving and controlling NEAT Flows.
The first step in establishing a flow with the NEAT System is to call a primitive to create and configure a Context. In the remainder of this document, the label P: is used to identify a primitive that may be called for a NEAT Context, and the label E: to identify an event provided by the NEAT System. Each primitive/event is associated with a particular NEAT Context. Most primitives specify the Context and provide a handle to the NEAT Flow upon which they operate, and the primitives and events for manipulating data can only be used after a NEAT Flow has been created.
The INIT_CTX primitive sets up the datastructures needed by the NEAT System.
After all network operations are completed it can free the context. It returns a pointer to the newly allocated and initialized NEAT context.
The FREE_CTX primitive is called when an created context is no longer needed. It frees the memory associated with the datastructures used by the NEAT System.
An application using the NEAT System needs to take the following steps to use the network after establishing a context:
An application needs to create and initialise a flow object before it can be used.
The INIT_FLOW primitive creates the essential data structures required to use a NEAT Flow. The application also needs to then call a primitive to associate functions with each of the events that it wishes to process.
Each NEAT Flow has a set of properties that are set at the flow initialisation time. The SET_PROPERTIES primitive sets properties for the NEAT Flow. Properties are related to Transport Features and Services. For instance: link-layer security, transport-layer security, certificate verification, certificate and key properties can be set at initialisation time are related to a Confidentiality Transport Feature. A flow can also have attributes that can be read by an application using maintenance primitives after a flow has been initialised.
The OPEN primitive opens a flow actively for transports that require a connection handshake (e.g., TCP, SCTP), and opens the flow passively for transports that do not (e.g., UDP, UDP-Lite). Calling P:OPEN alone may not actually have an effect “on the wire”, i.e., a P: ACCEPT at the peer may not be triggered by it. Since it is possible that the remote endpoint only returns when data arrives, this may only happen after the local host has called P: WRITE. (This does not result in a problem, since P: ACCEPT does not block).
The on_connected event indicates a successful connection setup. An application that receives this event can then use other primitives with this flow.
The OPEN_WITH_EARLY_DATA primitive allows data to be sent at the time when a flow is opened. To accommodate TLS 1.3 [I-D.ietf-tls-tls13] early data and the TCP Fast Open option [RFC7413], application data need to be supplied at the time of opening a NEAT Flow. This primitive opens a flow and sends early data if the protocol supports it. If the protocol chosen does not support early application data. The data will be buffered then sent after connection establishment, similar to calling P: WRITE. For this reason, in addition to the parameters of P: OPEN, this primitive also needs the same parameters as P: WRITE. The supplied data can be delivered multiple times (replayed by the network); an application must take this into account when using this function. This is commonly known as idempotence.
This section describes how an application prepares a flow to accept communication from another NEAT endpoint.
The ACCEPT primitive prepares a NEAT Flow to receive network data. UDP and UDP-Lite do not natively support a POSIX-style accept mechanism; in this case, NEAT emulates this functionality. P: ACCEPT can only return once data arrives, not necessarily after the peer has called P: OPEN (The callback-based implementation does not have this problem because P: ACCEPT does not block).
The on_connected event indicates a NEAT peer endpoint has connected, and other primitives can then be used.
The primitives in this section refer to actions that may be performed an open NEAT Flow, i.e., a NEAT Flow that was either actively established or successfully made available for receiving data. It permits an application to send and receive data-blocks over the API.
The on_writable event indicates there is buffer space available and the application may write new data using P:WRITE.
The WRITE primitive provide a NEAT Flow with a data block for transmission to the remote NEAT peer endpoint (with reliability limited by the conditions specified via pr_method, pr_value and the transport protocol used). NEAT Flows can support message delineation as a property of the NEAT Flow that is set via the INIT_FLOW primitive (§ 2.2.1). If a NEAT Flow supports message delineation, the data block is a complete message.
The on_all_written event indicates that all data requested to be written using P:WRITE has been sent.
The on_send_failure event may be returned instead of E:on_all_written when the NEAT System was temporarily unable to complete a P:WRITE call, and it not known that all data has been written.
The on_readable event indicates there is data available for the application that may be read using P:READ.
The READ primitive reads a data block from a NEAT Flow into a provided buffer. If a NEAT Flow supports message delineation, the data block is a complete message.
The primitives and events below are out-of-band calls that can be issued at any time after a NEAT Flow has been opened and before it has been terminated.
The CHANGE_TIMEOUT primitive adjusts the time after which a NEAT Flow will terminate if the written data could not be delivered. If this is not called, NEAT will make an automatic default choice for the timeout.
The SET_PRIMARY primitive is to be used with NEAT Flows that have multiple destination IP addresses, with protocols that do not use load sharing. It should not have an effect otherwise. This will overrule this general per-flow setting. If this is not called, the NEAT System will make an automatic default choice for the destination IP address.
The SET_LOW_WATERMARK primitive allows the application to limit the amount of unsent data in the underlying socket buffer. If set, NEAT will only execute E: WRITABLE when the amount of unsent data falls below the watermark. This allows applications to reduce sender-side queuing delay.
The SET_MIN_CHECKSUM_COVERAGE primitive allows an application to set the minimum acceptable checksum coverage length. This primitive only has effect for a received UDP-Lite datagram. A receiver that receives a UDP-Lite datagram with a smaller coverage length will not hand over the data to the receiving application. This is ignored for other protocols, where all data are fully covered by the checksum.
The SET_CHECKSUM_COVERAGE primitive allows an application to set the number of bytes covered by the checksum in a UDP-Lite datagram. This only has effect when the UDP-Lite protocol is selected.
The SET_TTL primitive sets the minimum IPv4 TTL or IPv6 Hop Count on a datagram that is required for it to be passed to the application.
The on_network_status_changed event informs the application that something has happened in the network; it is safe to ignore without harm by many applications. A status code indicates what has happened in accordance with a table that includes at least the following three values: 1) ICMP error message arrived; 2) Excessive retransmissions; 3) one or more destination IP addresses have become available/unavailable.
The GET_PROPERTY primitive allows an application to discover the value assigned to a property by the Policy Manager. Properties are expressed as part of policies and handled by the NEAT Policy Manager and can only be read by an application once a flow has been initialised.
These currently are:
This set of primitives and events are related to gracefully or forcefully closing a NEAT Flow, or being informed about this happening.
The CLOSE primitive terminates a NEAT Flow after satisfying all the requirements that were specified regarding the delivery of data that the application has already given to NEAT. If the peer still has data to send, it cannot then be received after this call. Data buffered by the NEAT System that has not yet been given to the network layer will be discarded.
The on_close event informs the application that a NEAT Flow was successfully closed. This can be received at any time for an active NEAT Flow.
The ABORT primitive terminates a connection without delivering remaining data.
The on_aborted event informs the application that the other side has aborted the NEAT Flow. The event can be received at any time for an active NEAT Flow.
The on_timeout event informs the application that the NEAT Flow is aborted because the default timeout has been reached before data could be delivered. This timeout adjusted by the P: CHANGE_TIMEOUT NEAT Flow maintenance primitive. The event can be received at any time for an active NEAT Flow.
Errors that occur within the NEAT System or that are notified by the network result in an on_error event:
This event notifies a hard or soft error to the upper layer using the NEAT System.
This document is about the design and usage of a transport API. The transport protocols accessed via this API each have security considerations.
The API may be used to request the use of security protocols accessed via the transport API.
This work was partially funded by the European Union's Horizon 2020 research and innovation programme under grant agreement No. 644334 (NEAT). The views expressed are solely those of the author(s).
XX RFC ED - PLEASE REMOVE THIS SECTION XXX
This memo includes no request to IANA.
-00 This is an individual draft for the IETF community, for consideration by the IETF TAPS WG.
-01 Contains corrections to INIT_FLOW; fixes to typos; and includes the Acknolwkedgment text omitted by mistake in -00.