path: root/docs/rfc.md

<!--- ---------------------------------------------------------------------  -->

%%%
title = "System of Lightweight Electronic Communication"
abbrev = "SOLEC"
ipr= "trust200902"
area = "Internet"
workgroup = "SOLEC Working Group"
submissiontype = "independent"
keyword = ["solec-draft"]

[seriesInfo]
name = "Internet-Draft"
value = "SOLEC"
stream = "independent"
status = "experimental"

[[author]]
initials = "bt"
role = "editor"
organization = "RCTT.net"
  [author.address]
  email = "bt@rctt.net"
%%%

.# Abstract

This document describes working principles, features and network protocol of
SOLEC system.

{mainmatter}

# Introduction

SOLEC is currently under development for PWR group project and as part of my
engineering thesis.

System of Lightweight Electronic Communication or SOLEC is a system for
decentralised communication designed for low-speed networks. It uses binary
protocol to keep required bandwidth as low as possible.

Current implementation works on top of TCP/IP stack. In future, SOLEC will be
adapted to work over LoRa.

## Decentralisation

Recurring problem with modern day instant messaging is its centralisation.
SOLEC solves is it in similar fashion to XMPP or SMTP. SOLEC servers exchange
messages between each other so the users using server A can reach out users
using server B.

## User to user communication

User can exchange messages with other users of the network if they are both in
their *contacts* group. Messages from untrusted users are not forwarded by the
server. If users are using different servers chat history is stored on both.

## Channels

Message can be send to a group of users called channel. Channels settings and
history is stored on a specific server. Users can access channels from servers
other than their own. To receive channel messages user have to join specific
channel.

# Network protocol

In current version session is provided by TCP connection. Security of
client-server connection can be achieved using TLS.

## Protocol Data Unit Structure

SOLEC is using Type Length Value (TLV) structure for data exchange.

~~~ ascii-art
  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
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |    Type       |             Length            |   Payload   ...
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~~~

Figure: SOLEC PDU Layout

* Type (8):
Payload type is indicated by 1 octet which gives 256 types that can be
represented.

* Length (16):
Payload length is 2 octets. It indicates length of the payload field.
The length does not include type and length fields.

* Payload (variable):
Payload stores set of fields determined by its type.

## Payload structure

Payload usually consist of one or more data fields but it is possible for
payload to be empty. Some payload types are used only to signal some event and
does not carry any data.

## Data types

Data types are basic types that are used in construction of more complex
payload types.

### Numeric types

Numeric types are Big-Endian. Numeric types names are taken from [Go language
spec](https://go.dev/ref/spec#Numeric_types). Following types are in use:

* uint8
* uint16
* uint32
* uint64

Number in numeric type name is number of bits used to encode this type.

### Timestamp

Uint64 containing Unix timestamp in UTC timezone.

~~~ ascii-art
  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
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                          Timestamp                            |
 |                                                               |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~~~


### String

String is prefixed with two octets indicating number of bytes that it occupies.
Text is encoded using UTF-8.

~~~ ascii-art
  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
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |             Length            |         UTF-8 string        ...
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~~~

Figure: String Layout

## Payload types

Payload type attributes describes following characteristics:

* R - Reserved: implementation should ignore payloads of this type
* S - Server: can be send only by a server
* C - Client: can be send only by a client
* E - Empty: signals an event but does not carry any data

| Type | Name       | Attributes |
|------|------------|------------|
| 0x00 |            | R          |
| 0x01 | Success    |  SCE       |
| 0x02 | Error      |  S         |
| 0x03 | Handshake  |  SC        |
| 0x04 | UserAuth   |   C        |
| 0x05 | Message    |  SC        |
| 0x06 | ServerAuth | S          |
| 0x07 | UserMode   | C          |
| 0x08 | History.   | C          |
| 0xFF | Test       | R          |

### Success

Payload is always empty for this type.

### Error

| Type  | Name       |
|-------|------------|
| uint8 | error_type |

#### Error types

| Type | Description                                               |
|------|-----------------------------------------------------------|
| 0x01 | Client auth failed. Invalid username or password.         |
| 0x02 | Not found. User or channel cannot access user or channel. |
| 0x03 | Unauthorized.                                             |

### Handshake

| Type  | Name      |
|-------|-----------|
| uint8 | ver_major |
| uint8 | ver_minor |
| uint8 | conn_type |

#### Connection types

`conn_type` specifies type of the connection. User connecting to server
should use `0x01`. If connection is initialize between two servers to exchange
message connection type should be `0x02`. Depending on connection type
different auth method will be used.

| Type | Connection type  |
|------|------------------|
| 0x01 | User -> Server   |
| 0x02 | Server -> Server |

### UserAuth

| Type   | Name     |
|--------|----------|
| string | username |
| string | password |

### ServerAuth

| Type   | Name     |
|--------|----------|
| string | name     |

### Message

| Type      | Name            |
|-----------|-----------------|
| string    | source_address  |
| string    | target_address  |
| timestamp | send_time       |
| string    | message_content |

### Usermode

Usermode payload is used for changing user settings related to channels. For
example: joining, leaving or setting privilages.

| Type   | Name         |
|--------|--------------|
| string | user_address |
| string | channel_name |
| uint8  | mode         |

#### Modes

| Type | Name       |
|------|------------|
| 0x00 | none       |
| 0x01 | in_channel |

### History

Read messages previously send to a specific channel. User has to member of the channel to perform this action. *since* field specifies start of time range for which history should be retrieved. *count* specifes how many messages should be returned in a single response. *GetHistory* is a locking sequence and it cannot be cancelled while in progress so *count* should be set relatively low. To get more messages use multiple requests with incremented *offset*.

Response is just a sequence of *Message*. Client should use *Timestamp* field of a *Message* to show them in corrent order.

| Type      | Name         |
|-----------|--------------|
| string    | channel_name |
| timestamp | since        |
| int64     | count        |
| int64     | offset       |

### Test

Test payload is used for encoder and decoders testing. Clients and servers
should ignore this kind of payload.

| Type      | Name  |
|-----------|-------|
| uint8     | num1  |
| timestamp | time1 |
| string    | str1  |
| uint16    | num2  |
| string    | str2  |
| uint32    | num3  |
| string    | str3  |
| uint64    | num4  |

## Sequential operations

Some operations require multiple rounds of communication.
In this case payloads are send in a sequence. Payload that is not part of this
specific operation (for example incoming message) cannot interrupt this process.

## Client-Server connection initialisation

~~~ ascii-art
+--------+                   +--------+
| Client |                   | Server |
+----+---+                   +----+---+
     |                            |
     | Initialise TCP connection  |
     +--------------------------->|
     |                            |
     | Send [Handshake]           |
     +--------------------------->|
     |                            |
     |                            +- If [ver_major] does not match
     |                            |  server protocol version close
     |                            |  the connection.
     |                            |
     | Send [UserAuth]            |
     +--------------------------->|
     |                            |
     | Send [Error 0x01]          |
     |<---------------------------+- If [username] or [password]
     |                            |  does not match and close
     |                            |  the connection.
     |                            |
     | Send [Sucesss]             |
     |<---------------------------+
~~~

## Exchanging messages between servers

Exchanging messages between SOLEC servers is a core concept behind the project.
Sending message to user residing on a different server require estabilishing a
connection between both servers.

### Authentication

Server authentication is crucial to prevent message spoofing and other forms of
abuse. Server cannot use same auth process as clients because that would require
creating account for each server on any other server which is impossible.
Possible solution are TLS or other public key based protocol.

As for now the issue remains open and server authorization uses mock
[ServerAuth] payload which specifies just the connecting server name.
This is obviously insecure.

### Server-Server connection initialisation

~~~ ascii-art
+--------+                   +--------+
| Server |                   | Server |
+----+---+                   +----+---+
     |                            |
     | Initialise TCP connection  |
     +--------------------------->|
     |                            |
     | Send [Handshake]           |
     +--------------------------->|
     |                            |
     |                            +- If [ver_major] does not match
     |                            |  server protocol version close
     |                            |  the connection.
     |                            |
     | Send [ServerAuth]          |
     +--------------------------->|
     |                            |
     | Send [Sucesss]             |
     |<---------------------------+
~~~

# Addresses

Message can be addressed to a single user or a channel.

* user@example.org
* #channel@example.org