diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile | 34 | ||||
| -rw-r--r-- | docs/rfc.md | 263 |
2 files changed, 297 insertions, 0 deletions
diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..6be417c --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,34 @@ +MMARK :=mmark +TXT := $(patsubst %.md,%.txt,$(wildcard *.md)) +XML := $(patsubst %.md,%.xml,$(wildcard *.md)) +HTML := $(patsubst %.md,%.html,$(wildcard *.md)) +PDF := $(patsubst %.md,%.pdf,$(wildcard *.md)) + +txt: $(TXT) + +%.txt: %.xml + xml2rfc --text --v3 -P $< + rm -f $(basename $<).xml + awk 'FNR<=4 || (FNR>=19 && FNR<=46) {next} {print}' $(basename $<).txt > tmp.txt + mv tmp.txt $(basename $<).txt + +html: $(HTML) + +%.html: %.xml + xml2rfc --html --v3 $< + rm -f $(basename $<).xml + +xml: $(XML) + +%.xml: %.md + $(MMARK) $< > $(basename $<).xml + +pdf: $(PDF) + +%.pdf: %.xml + xml2rfc --pdf --v3 $< + rm $(basename $<).xml + +.PHONY: clean +clean: + rm -f *.txt *.xml diff --git a/docs/rfc.md b/docs/rfc.md new file mode 100644 index 0000000..089d93f --- /dev/null +++ b/docs/rfc.md @@ -0,0 +1,263 @@ +<!--- --------------------------------------------------------------------- --> + +%%% +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. + +## Decentralization + +Recurring problem with modern day instant messaging is its centralization. +SOLEC solves is it in similair 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 octed which gives 256 types that can be +represented. + +* Length (16): +Payload length is 2 octets. It indicates lenght 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 typres are basic types that are used in construction of more comples +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 + +### 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: implementattion 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 | Auth | C | +| 0x05 | Message | SC | +| 0xFF | Test | R | + +### Success + +Payload is always empty for this type. + +### Error + +~~~ ascii-art + 0 + 0 1 2 3 4 5 6 7 + +-+-+-+-+-+-+-+-+ + | Error Type | + +-+-+-+-+-+-+-+-+ + ~~~ + +#### Error types + +| Type | Description | +|------|--------------------------------------------| +| 0x01 | Auth failed. Invalid username or password. | + +### Handshake + +~~~ ascii-art + 0 1 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | ver_major | ver_minor | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +~~~ + +### Auth + +~~~ ascii-art + 0 1 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | username (string) ... + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | password (string) ... + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +~~~ + +### Message + +~~~ 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 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | source_address (string) ... + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | target_address (string) ... + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | timestamp | + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | message_content (string) ... + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +~~~ + + + +### Test + +Test payload is used for encoder and decoders testing. Clients and servers +should ignore this kind of payload. + +~~~ 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 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | num1 (uint8) | time1 (timestamp) | + | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-| + | | str1 (string) ... + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | num2 (uint16) | str2 (string) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | num3 (uint32) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | str3 (string) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | num4 (uint64) | + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +~~~ + +## Sequential operations + +Some perations 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 incomming message) cannot interrupt this process. + +### Connection initialization + +- Client: Initialize TCP connection. +- Client: Send *handshake*. +- Server: If *major* version of protocol differs close the connection. +- Server: Otherwise send *handshake*. +- Client: Send *auth*. +- Server: If user credentials does not match send *error* with *auth_failed*. +- Server: Otherwise send *success*. |