| RFC draft-01 | XXX | August 2020 |
| Blum, et al. | Expires 14 February 2021 | [Page] |
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 14 February 2021.¶
Copyright (c) 2020 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.¶
This document describes the XXX file transport protocol which enables fast and robust file transfer via UDP.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].¶
Other terms used in this document are defined as follows:¶
The XXX Protocol is an application layer file transfer protocol to transmit one or multiple files from a server to a host. It is based on a client-server architecture, where the server stores the files and the client can request files. The focus of the protocol is on performance, robustness and on simplicity resulting in a small server state. The transport protocol used by XXX is UDP which allows high performance. To mitigate the issues when using UDP over TCP like data integrity and congestion control, XXX uses specific mechanisms to guarantee proper data transport also under difficult circumstances. Encryption or authorization mechanisms are currently not supported, can however be added later due to the highly flexible option fields. Data integrity is provided via UDP checksum as well as file checksums.¶
Client Server
| |
Give me file1, file2 |-------\ |
| ------->|
| |
| |
| /-------| Meta Info about file1
|<-------/-------| Offset=0 of file1
|<------- | Offset=3 of file1
| . |
| . |
| . |
| /-------| Offset=n of file1
|<------- |
ACK, I am at offset n |-------\ |
of file 1 | ------->|
| |
v v
¶
Figure 1: Very basic data flow of the protocol¶
To initiate the file transfer, the client starts with a Client Request message
containing all files it wants to download. After sending the request it will
start sending acknowledgement (ACK) messages periodically to tell the server
what data it has received. Besides the last received chunk of data, the ACK
message also contains resend entries of packets, which might have been lost as
well as different flags and data to get information about the RTT and flow
control.¶
Once the server receives a request message from the Client, it will start sending meta data followed by the content of each file sequentially. To minimize congestion, it will start slow and become faster, if the required ACK messages from the client are received. If the ACK messages contain many resend entries, however, the transmission speed will slow down and will resend those packets. If after a certain period of time no ACK message is received, it will drop the connection and remove the connection state. An XXX server SHOULD listen on port 2020 (decimal) for incoming requests.¶
In the following the different message layouts are explained.¶
Each message contains a global header to enable server and clients to quickly parse and handle messages. This header has a length of at least three bytes. The global header looks as follows:¶
It starts with the version of the protocol which takes the first four bits of the first byte. The details of the versioning are explained in Section 6.1.1.¶
The second four bits of the first byte contain a message ID. The message ID indicates which type of message the packet contains. All valid message types are described in the following sections together with a unique identifier, which MUST be used as the message ID in the header.¶
An 8 bit ACK number MUST be sent by clients to the server in the second byte
and is incremented for each message. This allows the server to tell the client
the last ACK received within a small window, so the client can calculate the
round-trip time (RTT). Thus the Server MUST always set this value to the ACK
number it saw in the last client ACK message. The client continuously calculates
the RTT by remembering the time an ACK number was first sent and subtracting it
from the time when it receives this ACK number in a message sent by the server
for the first time.¶
The third byte of the header contains the number of options following the header. The details of options are explained in Section 6.1.2.¶
The data integrity of a single packet is guaranteed by the UDP checksum which MUST be enabled.¶
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |Version| MsgID | ACK Number | # Options | Options ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+¶
Figure 2: Global header of all messages¶
Version - 4 bit unsigned integer specifying the version used for this
message. This document describes version 1.¶
MsgID - 4 bit unsigned integer specifying the message ID.¶
ACK Number - 8 bit unsigned integer that distinguishes this packet from
packets sent within a small window before and after this message. The server
will then use its last received ACK number in its next messages, so that the
client can use that to determine the RTT.¶
# Options - 8 bit unsigned integer specifying the number of options in the
Options field.¶
Options - TLV-encoded options (see Section 6.1.2 below).¶
The version of a message is based on the protocol version implemented by the
client/server software. If the client sends a message with a version not
supported by the server, then the server SHOULD send a Close Connection
message to the client containing the reason code Unsupported Version (0x2).
The version of the Close Connection message MUST be the lowest version the
server supports in case the version of the client's message is lower than any
of the supported versions of the server and the highest version the server
supports otherwise.¶
If the version of the client message is supported, then the server MUST act accordingly to that version. During the transmission the client and the server MUST NOT change the used version.¶
A packet header may contain zero or more, but at maximum 255, type-length-value (TLV) encoded options. The number of options MUST be given in the second byte of the header. Each option MUST contain three fields: the first byte holds the type of the option, the second byte contains the length of the option value in bytes. Afterwards follow as many bytes as indicated by the second field to hold the actual option value. Option types MUST be registered in this specification or a future version of this specification. Option types MAY be different in different versions. Currently there are no option types specified and implementations SHOULD be able to operate without using any options.¶
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Option Type | Opt Length | Option Value ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+¶
Figure 3: TLV-encoding of header options¶
To initiate a download, the client MUST send a client request message to the
server. The message ID for a client request message is 0x0. In a client
request, the first field after the header contains four bytes for the maximum
transmission rate, at which the client is willing to operate. The maximum
transmission rate MUST be given in messages/second (which is roughly equivalent
to KiB/s). See Section 8.1 for more information about the maximum
transmission rate.¶
The protocol also supports the download of multiple files. Thus a client needs
to indicate how many and which files it wants to download from a server. The
first two bytes after the Maximum Transmission Rate contain the number of
files requested. The number of files is then succeeded by exactly that number of
file descriptors (see Section 6.2.1) which describe the requested files.¶
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Maximimum Transmission Rate | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | File Count | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | File Descriptors | | [variable length] | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+¶
Figure 4: Client Request Message¶
MsgID: 0x0¶
Maximum Transmission Rate: 32 bit unsigned integer specifying the maximum
transmission rate a client is willing to operate at in messages/second.
Transmission rates may be updated in following ACK packets.¶
File Count: 16 bit unsigned integer specifying the number of file
descriptors in the request. This specifies the total number of files being
requested.¶
File Descriptors: Array of file descriptors with the length File Count.
Each file descriptor describes one requested file.¶
A file descriptor describes one file being fetched and is part of the Client
Request message. Random access of files is supported by this protocol, so an
offset can be set. This also allows the continuation of a previously failed
download. A full file path is then provided, along with the length of the
string describing the path.¶
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Offset ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ... |Filename Len ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ... Filename Len| | +-+-+-+-+-+-+-+-+ | | Filename | | [variable length] | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+¶
Figure 5: File Descriptor frame¶
For every file requested by the client, the server is going to send one message
containing metadata about the file. The message ID of a metadata messages is
0x1. If the server can not serve a file for any reason, the reason MUST be set
in the status byte of this message. If status is set to 0x0, the metadata
serves as a confirmation to the client that the data for the requested file is
about to be sent. Special error status codes are specified below. All nonzero
status messages imply the file will be skipped by the server.¶
Additionally, the last field of the metadata message contains a checksum, which can be used to verify the correct transmission of a file and to check for changes after a resumed download. The checksum field MUST be set to the 16 byte message digest of the MD5 checksum of the requested file ([RFC1321]). The checksum MUST be set to zero, if the server cannot serve the file, due to any reason as described in Section 7.¶
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Pad\Reserved | Status | File Number | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | File Size (in byte) | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Checksum | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+¶
Figure 6: Server Metadata Message¶
MsgID: 0x1¶
Status¶
File Number: 16 bit unsigned integer. This index corresponds to the index
in the client request file descriptors. For example, if the file
descriptors were [a, b], then file a would have file number 0 and
file b would have file number 1.¶
File Size: 64 bit unsigned integer specifying the length of the file.¶
Checksum: A 16 byte MD5 message digest to validate contents of the file.¶
The Server Payload contains binary data of a file being downloaded. A payload
message MUST contain exactly one chunk of data, if it is not the last payload
message of a specific file. If a payload message is the last part of a file, it
MUST be as big as the rest of the file. The server MUST save client session
information so it can uniquely identify a file based on the file number and
connection port and IP of the client. The message ID of a payload message is
0x2. The offset is in the granularity of chunks, thus is a 56 bit unsigned
integer.¶
The server MUST initially send payloads in the order in which they were
requested from the client. In other words, payload at offset N+1 of a file
MUST be sent after payload at offset N and all payload packets of file N+1
MUST be sent after all payload packets of file N.¶
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | File Number | Offset ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ... Offset ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ... Offset | ... +-+-+-+-+-+-+-+-+ | | Payload | | [variable length] | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+¶
Figure 7: Server Payload Message¶
The client MUST send a Client ACK message at least every 500ms starting
immediately after sending the Client Request. The message ID for the client ACK
is 0x3. Although the client is restricted to send an ACK every 500ms, it is
free to send more ACK packets to improve performance by accelerating resending
chunks. The Status MUST be set if the conditions described below are met. The
Maximum Transmission Rate specifies the maximum transmission rate the client
can handle from the server in messages/second. More information about this can
be found in Section 8.1. The Offset is in the granularity of chunks, thus
is 56 bits and MUST point to the highest offset of the file with the highest
file number, for which a payload packet has been received. After the offset
field, the client MAY add a list of Resend Entries to indicate that some
chunks are missing and should be sent again by the server. The structure of
Resend Entries is described in Section 6.5.1. In section
Section 6.5.2 the structure of a Client ACK with the resend entries is
visualized.¶
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | File Number | Status | ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ... Maximum Transmission Rate | ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ... Offset ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ... Offset | Resend Entries [var. length] ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+¶
Figure 8: Client ACK Message¶
Note that the number of resend entries in the packet can be calculated from the UDP packet size.¶
MsgID: 0x3¶
File Number: Highest file number for which a payload packet has been
received. 16 bit unsigned integer, same as in the Server Metadata message.¶
Status¶
Maximum Transmission Rate: 32 bit unsigned integer describing the maximum
transmission rate, same as in Client Request.¶
Offset: Unsigned 56 bit integer describing the number of the highest
received chunk in the file identified by File Number.¶
Resend Entries: List of Resend Entry objects that describe missing data in
the received file.¶
A resend entry describes a contiguous chunk of missing data. It consists of a
File Number, in case the missing data is from a previous file where the server
has already reached the EOF in file transmission. The offset specifies the
position in the file at which the missing data starts in chunks. Length
specifies how many contiguous chunks are missing.¶
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | File Number | ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ... Offset ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ... | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+¶
Figure 9: Resend Entry¶
File Number - 16 bit unsigned integer, same as in the Server Metadata
message.¶
Offset - 56 bit unsigned integer describing the offset into the file in
chunks.¶
Length - Number of contiguous missing chunks. If more than 255 chunks are
missing, multiple resend entries are needed. If it is unknown how many chunks
are missing (e.g. due to missing metadata), Length will be set to 0.¶
In this section 2 example scenarios and their corresponding ACK messages are shown. In both cases files 0 to 3 were fully received.¶
Scenario 1, Metadata of all files received:¶
_________________________________________
Chunks of file no 4: |__0__|__1__|__2__|__3__|__4__|__5__|__6__|
|----------------received-----------|
_____________________________________________________________________________
Chunks of file no 5: |__0__|__1__|__2__|__3__|__4__|__5__|__6__|__7__|__8__|__9__|__10_|__11_|__12_|
|----- received --| |--received-| |recv-|
¶
The Client Ack would look like that:¶
5, Offset: 8¶
0x00 (Nothing special)¶
[(file, offset, length)] = [(4, 6, 1), (5, 3, 2), (5, 7, 1)]¶
Scenario 2, Metadata of file 4 and 5 missing:¶
___________
Chunks of file no 4: |__0__|__1__|...?
|-received--|
_____________________________________________________________________________
Chunks of file no 5: |__0__|__1__|__2__|__3__|__4__|__5__|__6__|__7__|__8__|__9__|__10_|__11_|__12_|
|----- received --| |--received-| |recv-|
¶
The Client Ack would look like that:¶
For politeness and convenience, servers and clients SHOULD send close connection messages to notify the other party to free all session related state immediately upon receival, rather than wait for the connection to timeout. The server SHOULD also send close connection messages to clients with improper or expired requests. All close connection requests are optional and are not guaranteed to be received.¶
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Reason | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+¶
Figure 10: Close Connection Message¶
If the server or the client is shut down in a controlled manner due for reasons
that do not fit into the reasons below, it SHOULD close all currently
established connections by sending a Close Connection Message. The reason
field in this message MUST be Unspecified/No Reason Provided (0x0).¶
If the server or the client application is shut down during a transmission, it
SHOULD close all currently established connections by sending a Close
Connection Message with the reason Application closed (0x1).¶
If the server does not support the version of the client specified in the main
header, it SHOULD close the connection by sending a Close Connection Message
with the reason Unsupported Version (0x2). This does not hold for the
options which can be appended to the global header. Options are designed as
optional features. Thus the server can ignore the option if it does not support
the option type.¶
If the server receives a message other than a Client Request from a client
(identified by the remote IP address and port) it does not know it SHOULD
respond with a Close Connection Message with the reason Unknown Request
(0x3). This is mostly due to timeouts in which case the server dropped all
connection state.¶
If a connection got dropped, the client can try to establish a new connection
with the offsets of the half downloaded files. The first message of the server
will then be the metadata of the file. If the checksum is different than the one
of the previous request, the file has changed in between both requests. The
client SHOULD therefore drop the connection by sending a Close Connection
Message with the reason Wrong Checksum (0x4) and start a new request.¶
If the client receives all requested files with no data loss, the client SHOULD
notify the server by sending a Close Connection Message with the reason
Download Finished (0x5). Once the server's file offset reaches the end of
file, it SHOULD wait for ACKs with resend request until the standard timeout
period has expired.¶
Since the client sends Client ACK Messages at least every 500ms, the server
SHOULD wait for a period of at least 3 seconds for new Client ACK Messages
before closing the connection and dropping the client state. The server SHOULD
also send a close connection message with the reason Timeout (0x6),
notifying the client of a timeout.¶
In addition, once a connection is established, the server MUST continually send
messages to the client. The client SHOULD wait a period of at least 3 seconds
before closing the connection and attempting to start a new connection with
adjusted offsets. The client SHOULD also send a close connection message with
a reason of 0x6, notifying the server of a timeout.¶
If either the client or server wants to cancel a connection early, they SHOULD send a close connection message, so that the other side can free up the associated session state. However, due to the timeout, if the close connection message is lost, the other side will eventually time out.¶
If the client requests a file at an offset that is larger than the file, the
server MUST send the metadata for this file with the flag File too small
(0x04).¶
The client expects the server to start the data transmission after it has sent a client request message. The request message can however get lost, in which case the client won't receive any messages from the server. The client should wait for a server response for a reasonable time. If no message is received, the client SHOULD stop listening on its current port, start listening on another port, and resend the client request message. The client MAY increase the time until the request is retransmitted exponentially or otherwise.¶
XXX has mechanisms to prevent overloading the network, the receiver, or the
sender. It consists of two parts: The client-controlled flow control and the
congestion control. Both values are calculated independently of each other and
the minimum of both values will be used by the server as its maximum
transmission rate: server sending rate = min(flow control, congestion
control). The server MUST NOT send more packets per second than the minimum of
both values. In the following two sections both mechanisms are specified.¶
Flow control guards the clients from being overloaded. The client specifies a
maximum transmission rate in both the Client Request and each Client ACK
message. The unit of this field is number of messages/second. This rate SHOULD
be an estimate of the maximum data rate that the client is able to process. The
server MUST NOT transmit more messages (and therefore Server Payload messages)
per second than this field of the last received message specifies. An exception
to this rule is the special value 0: The client can set the maximum transmission
rate to 0 to signal that it does not want to limit the server. In this case, the
server sending rate is solely determined by congestion control.¶
The client is free to adapt this value throughout the protocol execution, e.g., to fit its memory resources. The server MUST update the maximum transmission rate with each received packet.¶
The purpose of congestion control is to prevent overloading the network. This protocol uses packet loss indicated by the resend entries in the ACK messages as an indicator that the network's performance ceiling is reached.¶
The server has to maintain a sending rate. That sending rate MAY be small at the
start of a connection but SHOULD increase with every Client ACK that does not
contain a resend entry. If the server receives a Client ACK with one or more
resend entries, it MUST reduce its sending rate.¶
The security of a software system is defined on the basis of certain security goals. Those are typically confidentiality, integrity, availability, authenticity, accountability, and non-repudiation.¶
The XXX protocol takes insufficient measures to realize any of those properties. Any of them is violated in at least one way:¶
Confidentiality, integrity, and authenticity could be offered by incorporating an encryption and authentication scheme. An obvious option would be to utilize TLS to setup a secured channel; Datagram Transport Layer Security (DTLS) [RFC6347] adapts TLS to UDP. Other possibilites include the usage of protocols such as IPsec or the usage of an SSH tunnel.¶
While an encryption scheme would also provide a mitigation for some availability and denial-of-service (DoS) attacks, further modifications to the XXX protocol would be needed. Two easy to exploit attacks along with a potential mitigation are described in the following.¶