SethVFS

Details

Being a file transfer protocol, SethVFS implements a number of low-level filesystem-like operations including open, read, seek, close, get directory list, etc. The Kodi application calls into these methods when it needs to retrieve information about a file. Behind the scenes, unbeknownst to Kodi, the SethVFS add-on establishes and maintains a TCP connection to the server, performing two-way session-based authenticated encryption of all information exchanged between the client and the server. This means that when Kodi issues a file read operation for example, the add-on pipes this request to a remote server, and the server is what is actually performing the file I/O. The server then returns the requested data to the client. In addition, a special handshake is employed to ensure maximum trust between the client and server while also preventing replay and DoS attacks. If at any point the session becomes corrupt, the bad data is thrown away and the session is terminated.

In the first version of the protocol, a single session was maintained and the client and server took turns in a sequential request/response pattern. When transferring files, this results in underutilization of resources due to significant pipeline stalls. In the figure below, the pink squares represent requests from the client and the green squares represent responses from the server.

This has been resolved in the second version of the protocol, without sacrificing the benefits of session-based cryptography. After the handshake, the session is split into two streams: one for upstream traffic (e.g. client-to-server) and one for downstream traffic (e.g. server-to-client). The result is that both the client and server can make full use of their respective resources. This better matches the TCP protocol and allows for pipelining, as demonstrated below. As proven during testing, the new version is able to fully saturate a gigabit link.

The client always initiates the connection and sends metadata composed of the client ID, server ID, a current timestamp and a random 256-bit nonce. The server validates the server ID, timestamp and tag, and then replies with a random 256-bit nonce of its own. Once the client validates the tag from the server, the client fully trusts the server. The client then responds with a tag that authenticates the session thus far; once validated, the server fully trusts the client and the session is established. From this point forward, the client initiates a request (e.g., a file operation), and the server replies to the request. This request and response flow is repeated as many times as needed. The server maintains state per connected client (e.g. a table of open file handles, etc.).

Demonstration

SethVFS appears as a custom protocol with prefix "sethvfs://" in Kodi. The path resembles that of a standard web address or file share. In this example, I am mounting a music share via SethVFS.

Kodi can stream the content as if it is a local file; 100% of the data is protected by the authenticated encryption mode described above.