3. Whitepaper 📃

This sections explains the inner workings of the project.

Contents

• Technologies
• Network Architecture
• Solution Structure
• Hosta (Core Library)
  • Crypto
  • Tools
  • Net
  • RPC
  • API

Technologies 🚀

This project using the following languages / frameworks:

• C# 9
• .NET 5
• WPF (desktop client)
• SQLite (node)

It also uses the following NuGet packages:

• Json.NET - fast and reliable JSON serialization
• sqlite-net - a simple, cross platform ORM for SQLite

Many thanks to the library maintainers for making this project possible!

Network Architecture 🏰

As mentioned earlier, there are two classes of device on the Hosta network.

1. Nodes - always-on servers, responsible for controlling the data of a user
2. Clients - user interfaces, responsible for fetching and displaying data from nodes

A sample architecture is shown below, with each user having a node and a single client.

User IDs

Each user is identified by a unique hex ID, generated from the hash of their public key.

IDAR

Identity Address Resolver

Responsible for finding the node address of a given ID (a replacement for traditional DNS)

As nodes have a high uptime, they help power the IDAR service. When a client wishes to get the location of a friend's node, they will ask their own node for the address. Their own node will then resolve the query, returning the address to the client.

There are five main mechanisms that IDAR could use, in order of increasing complexity:

• Manual IP entry (impractical)
• Full mesh broadcasting (heavy on storage)
• Friend broadcasting w/ crash-recovery (light on storage, but very vulnerable to partitions)
• Blockchain (less vulnerable to partitions, but heavy on the CPU)
• Distributed hash table (light on storage, efficient queries, but hard to implement)

The ones that have been implemented have been ticked off.

Solution Structure 🔧

The solution is divided into 3 main projects - a client application, a node program, and a core library (used by both the client and the node).

Note: Consider "x->y" to mean "x is dependant on y and y is not dependant on x".

"x->y->z" => "x->z"

Hosta (Core Library) 🍀

The core library is responsible for definining the communication between devices on the network. Using it, anyone can create their own node or client!

Below is a diagram that outlines the structure:

Note: The diagram has simplifications to prevent visual clutter - the actual workings are a little less nice to look at!

Crypto

The Hosta.Crypto sub-namespace handles the common cryptographic operations across the namespace. It uses the following primitives from System.Security.Cryptography:

• AesGcm - symmetric encryption
• RandomNumberGenerator - CSPRNG
• ECDH - key exchanging
• ECDsa - digital signatures
• HMACSHA512 - symmetric ratcheting
• SHA256 - hashing

Tools

The Hosta.API sub-namespace provides commonly used tools. At the moment, these include:

• AccessQueue
  • an asynchronous queue, used to control access to a resource
• Transcoder
  • provides text encoding / decoding functionality

Net

The Hosta.Net sub-namespace builds upon System.Net.Sockets to allow secure, authenticated, message-based (as opposed to stream-based) communication.

It uses a "layer" structure:

• Socket[Client/Server/Messenger]
  • wraps the default Socket APM functions with TAP functions
  • splits the socket stream into messages (using length prefixing)
• Protected[Client/Server/Messenger]
  • performs an ECDH key exchange
  • encrypts the connection using AES GCM
  • provides backwards secrecy with KDF Ratchets (forwards secrecy may yet be implemented)
• Authenticated[Client/Server/Messenger]
  • allows a client and server to authenticate each other
  • translates between strings and byte arrays

This layer structure allows resilient and reliable communications, without relying on tradional methods (such as certificate authorities or 2WSSL).

Disclaimer: Don't use the Protected or Authenticated classes for anything serious. I understand enough about cryptography to realise I know nothing :)

RPC

The Hosta.RPC sub-namespace builds upon Hosta.NET to allow for remote procedure calls in the form of Call(string proc, string args).

It consists of two main classes:

• RPServer
  • receives RPCalls and forwards them to a given ICallable
  • sends back an RPResponse when the call has finished
• RPClient
  • allows a client to send an RPCall to the server
  • returns the result from an RPResponse when the call has finished (or throws an exception if remote execution failed)

API

The Hosta.API sub-namespace provides the main functionality for the library, by building off Hosta.RPC.

There are three main classes:

• API
  • an abstract class which acts specifies the remote procedures which can be called on the node
• RemoteAPIGateway
  • translates any incoming RPCall into an API function call
  • returns the result to the RPServer
• LocalAPIGateway
  • translates API function calls into RPClient calls
  • translates the response from the RPClient into meaningful data

There is also a Hosta.API.Data sub-namespace which specifies the data structures for API requests and responses.