From d63176e22d21e347cf1c197084afe8eb1d5376b4 Mon Sep 17 00:00:00 2001 From: bt Date: Sat, 18 Apr 2026 23:12:11 +0200 Subject: [docs] Update protocol docs --- docs/protocol.ksy | 126 +++++++++ docs/protocol.svg | 827 +++++++++++++++++++++++++++++------------------------- docs/rfc.html | 164 ++++++++--- docs/rfc.md | 48 ++-- docs/rfc.txt | 56 ++-- 5 files changed, 759 insertions(+), 462 deletions(-) create mode 100644 docs/protocol.ksy (limited to 'docs') diff --git a/docs/protocol.ksy b/docs/protocol.ksy new file mode 100644 index 0000000..169ba18 --- /dev/null +++ b/docs/protocol.ksy @@ -0,0 +1,126 @@ +meta: + id: solec + file-extension: hex + endian: be + +doc: SOLEC protocol +doc-ref: https://git.rctt.net/solec/plain/docs/protocol.svg?h=main + +seq: + - id: type_payload + type: u1 + enum: payload_type + - id: len_payload + type: u2 + - id: payload + size: len_payload + type: + switch-on: type_payload + cases: + 'payload_type::success': success + 'payload_type::error': error + 'payload_type::handshake': handshake + 'payload_type::user_auth': user_auth + 'payload_type::server_auth': server_auth + 'payload_type::message': message + 'payload_type::test': test + +enums: + payload_type: + 0x01: success + 0x02: error + 0x03: handshake + 0x04: user_auth + 0x05: message + 0x06: server_auth + 0xFF: test + + error_type: + 0x01: user_auth_failed + 0x02: not_found + + conn_type: + 0x01: user_conn + 0x02: server_conn + +types: + string: + doc: UTF-8 encoded string. + seq: + - id: len_payload + type: u2 + - id: payload + type: str + size: len_payload + encoding: UTF-8 + + success: + doc: Send from server if operation succeded. + + error: + doc: Senf from server if operation failed. + seq: + - id: error_code + type: u1 + enum: error_type + + handshake: + doc: | + Handshake is sent by the client during connection initialization. + If protocol_ver_major is different than version used by the server + connection will be aborted. + seq: + - id: proto_ver_major + type: u1 + - id: proto_ver_minor + type: u1 + - id: conn_type + type: u1 + enum: conn_type + + user_auth: + seq: + - id: name + type: string + - id: pass + type: string + + server_auth: + seq: + - id: name + type: string + + message: + doc: | + Source and target fields are addresses in user@server format. + seq: + - id: source + type: string + - id: target + type: string + - id: timestamp + doc: Set just before sending the message. + type: u8 + - id: content + type: string + + test: + doc: Test payload, used for parsers testing + seq: + - id: num1 + type: u1 + - id: time1 + type: u8 + - id: str1 + type: string + - id: num2 + type: u2 + - id: str2 + type: string + - id: num3 + type: u4 + - id: str3 + type: string + - id: num4 + type: u8 + diff --git a/docs/protocol.svg b/docs/protocol.svg index 20a9119..b029409 100644 --- a/docs/protocol.svg +++ b/docs/protocol.svg @@ -4,489 +4,542 @@ - - - + + + cluster__solec - -Solec + +Solec -cluster__auth - -Solec::Auth +cluster__error + +Solec::Error -cluster__error - -Solec::Error +cluster__handshake + +Solec::Handshake -cluster__handshake - -Solec::Handshake +cluster__message + +Solec::Message -cluster__message - -Solec::Message +cluster__server_auth + +Solec::ServerAuth cluster__string - -Solec::String + +Solec::String cluster__success - -Solec::Success + +Solec::Success cluster__test - -Solec::Test + +Solec::Test + + +cluster__user_auth + +Solec::UserAuth solec__seq - - -pos - - -size - - -type - - -id - -0 - -1 - -u1→PayloadType - -type_payload - -1 - -2 - -u2be - -len_payload - -3 - -... - -switch (type_payload) - -payload + + +pos + + +size + + +type + + +id + +0 + +1 + +u1→PayloadType + +type_payload + +1 + +2 + +u2be + +len_payload + +3 + +... + +switch (type_payload) + +payload - + solec__seq:type_payload_type->solec__seq:payload_type - - + + solec__seq_payload_switch - - -case - - -type - -:payload_type_auth - -Auth - -:payload_type_error - -Error - -:payload_type_handshake - -Handshake - -:payload_type_message - -Message - -:payload_type_success - -Success - -:payload_type_test - -Test + + +case + + +type + +:payload_type_error + +Error + +:payload_type_handshake + +Handshake + +:payload_type_message + +Message + +:payload_type_server_auth + +ServerAuth + +:payload_type_success + +Success + +:payload_type_test + +Test + +:payload_type_user_auth + +UserAuth solec__seq:payload_type->solec__seq_payload_switch - - - - - -auth__seq - - -pos - - -size - - -type - - -id - -0 - -... - -String - -name - -... - -... - -String - -pass - - - -solec__seq_payload_switch:case0->auth__seq - - + + - + error__seq - - -pos - - -size - - -type - - -id - -0 - -1 - -u1→ErrorType - -error_code + + +pos + + +size + + +type + + +id + +0 + +1 + +u1→ErrorType + +error_code - -solec__seq_payload_switch:case1->error__seq - - + +solec__seq_payload_switch:case0->error__seq + + - + handshake__seq - - -pos - - -size - - -type - - -id - -0 - -1 - -u1 - -proto_ver_major - -1 - -1 - -u1 - -proto_ver_minor + + +pos + + +size + + +type + + +id + +0 + +1 + +u1 + +proto_ver_major + +1 + +1 + +u1 + +proto_ver_minor + +2 + +1 + +u1→ConnType + +conn_type - -solec__seq_payload_switch:case2->handshake__seq - - + +solec__seq_payload_switch:case1->handshake__seq + + - + message__seq - - -pos - - -size - - -type - - -id - -0 - -... - -String - -source - -... - -... - -String - -target - -... - -8 - -u8be - -timestamp - -... - -... - -String - -content + + +pos + + +size + + +type + + +id + +0 + +... + +String + +source + +... + +... + +String + +target + +... + +8 + +u8be + +timestamp + +... + +... + +String + +content + +solec__seq_payload_switch:case2->message__seq + + + + + +server_auth__seq + + +pos + + +size + + +type + + +id + +0 + +... + +String + +name + + -solec__seq_payload_switch:case3->message__seq - - +solec__seq_payload_switch:case3->server_auth__seq + + success__seq - - -pos - - -size - - -type - - -id + + +pos + + +size + + +type + + +id solec__seq_payload_switch:case4->success__seq - - + + test__seq - - -pos - - -size - - -type - - -id - -0 - -1 - -u1 - -num1 - -1 - -8 - -u8be - -time1 - -9 - -... - -String - -str1 - -... - -2 - -u2be - -num2 - -... - -... - -String - -str2 - -... - -4 - -u4be - -num3 - -... - -... - -String - -str3 - -... - -8 - -u8be - -num4 + + +pos + + +size + + +type + + +id + +0 + +1 + +u1 + +num1 + +1 + +8 + +u8be + +time1 + +9 + +... + +String + +str1 + +... + +2 + +u2be + +num2 + +... + +... + +String + +str2 + +... + +4 + +u4be + +num3 + +... + +... + +String + +str3 + +... + +8 + +u8be + +num4 solec__seq_payload_switch:case5->test__seq - - + + + + + +user_auth__seq + + +pos + + +size + + +type + + +id + +0 + +... + +String + +name + +... + +... + +String + +pass + + + +solec__seq_payload_switch:case6->user_auth__seq + + string__seq - - -pos - - -size - - -type - - -id - -0 - -2 - -u2be - -len_payload - -2 - -len_payload - -str(UTF-8) - -payload - - - -auth__seq:name_type->string__seq - - + + +pos + + +size + + +type + + +id + +0 + +2 + +u2be + +len_payload + +2 + +len_payload + +str(UTF-8) + +payload - + -auth__seq:pass_type->string__seq - - +message__seq:source_type->string__seq + + -message__seq:source_type->string__seq - - +message__seq:target_type->string__seq + + -message__seq:target_type->string__seq - - +message__seq:content_type->string__seq + + - + -message__seq:content_type->string__seq - - +server_auth__seq:name_type->string__seq + + string__seq:len_payload_type->string__seq:payload_size - - + + test__seq:str1_type->string__seq - - + + test__seq:str2_type->string__seq - - + + test__seq:str3_type->string__seq - - + + + + + +user_auth__seq:name_type->string__seq + + + + + +user_auth__seq:pass_type->string__seq + + diff --git a/docs/rfc.html b/docs/rfc.html index 84b5c0a..99a6a34 100644 --- a/docs/rfc.html +++ b/docs/rfc.html @@ -1220,7 +1220,7 @@ li > p:last-of-type:only-child {
bt -Expires 16 October 2026 +Expires 20 October 2026 [Page]
@@ -1233,12 +1233,12 @@ li > p:last-of-type:only-child {
SOLEC
Published:
- +
Intended Status:
Experimental
Expires:
-
+
Author:
@@ -1274,7 +1274,7 @@ SOLEC system.

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 16 October 2026.

+ This Internet-Draft will expire on 20 October 2026.

-
+
-

-2.4.4. Auth +

+2.4.4. UserAuth

@@ -1739,13 +1756,35 @@ different auth method will be used.
Table 6
-
+
-

-2.4.5. Message +

+2.4.5. ServerAuth

+ + + + + + + + + + + + +
Table 7
TypeName
stringname
+
+
+
+
+

+2.4.6. Message +

+ + @@ -1774,14 +1813,14 @@ different auth method will be used.
-
+

-2.4.6. Test +2.4.7. Test

-

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

-
Table 8
Type
- +

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

+
Table 8
+ @@ -1835,12 +1874,14 @@ should ignore this kind of payload.

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.

- +
+
+

+2.6. Client-Server connection initialisation +

+
+--------+                   +--------+
 | Client |                   | Server |
 +----+---+                   +----+---+
@@ -1851,19 +1892,72 @@ specific operation (for example incoming message) cannot interrupt this process.
      | Send [Handshake]           |
      +--------------------------->|
      |                            |
-     |                            +- If [ver_major] does not match server
-     |                            |  protocol version close the connection
+     |                            +- If [ver_major] does not match
+     |                            |  server protocol version close
+     |                            |  the connection.
      |                            |
-     | Send [Auth]                |
+     | Send [UserAuth]            |
      +--------------------------->|
      |                            |
      | Send [Error 0x01]          |
-     |<---------------------------+- If [username] or [password] does not match
-     |                            |  and close the connection
+     |<---------------------------+- If [username] or [password]
+     |                            |  does not match and close
+     |                            |  the connection.
+     |                            |
+     | Send [Sucesss]             |
+     |<---------------------------+
+
+
+
+
+
+
+

+2.7. 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.

+
+
+

+2.7.1. 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.

+
+
+
+
+

+2.7.2. Server-Server connection initialisation +

+
+
+--------+                   +--------+
+| Server |                   | Server |
++----+---+                   +----+---+
+     |                            |
+     | Initialise TCP connection  |
+     +--------------------------->|
+     |                            |
+     | Send [Handshake]           |
+     +--------------------------->|
+     |                            |
+     |                            +- If [ver_major] does not match
+     |                            |  server protocol version close
+     |                            |  the connection.
+     |                            |
+     | Send [ServerAuth]          |
+     +--------------------------->|
      |                            |
      | Send [Sucesss]             |
      |<---------------------------+
-
+
diff --git a/docs/rfc.md b/docs/rfc.md index 8296cfa..854d737 100644 --- a/docs/rfc.md +++ b/docs/rfc.md @@ -180,7 +180,6 @@ Payload is always empty for this type. |------|-----------------------------------------------------------| | 0x01 | Client auth failed. Invalid username or password. | | 0x02 | Not found. User or channel cannot access user or channel. | -| 0x03 | Server auth failed. Unknown name. | ### Handshake @@ -246,7 +245,7 @@ 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 +## Client-Server connection initialisation ~~~ ascii-art +--------+ +--------+ @@ -259,20 +258,40 @@ specific operation (for example incoming message) cannot interrupt this process. | Send [Handshake] | +--------------------------->| | | - | +- If [ver_major] does not match server - | | protocol version close the connection + | +- If [ver_major] does not match + | | server protocol version close + | | the connection. | | - | Send [UserAuth] | + | Send [UserAuth] | +--------------------------->| | | | Send [Error 0x01] | - |<---------------------------+- If [username] or [password] does not match - | | and close the connection + |<---------------------------+- 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 @@ -286,22 +305,13 @@ specific operation (for example incoming message) cannot interrupt this process. | Send [Handshake] | +--------------------------->| | | - | +- If [ver_major] does not match server - | | protocol version close the connection + | +- If [ver_major] does not match + | | server protocol version close + | | the connection. | | | Send [ServerAuth] | +--------------------------->| | | - | Send [Error 0x03] | - |<---------------------------+- If [name] is not present in known public - | | keys list. - | | | Send [Sucesss] | |<---------------------------+ ~~~ - -## Server to server operation - -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. diff --git a/docs/rfc.txt b/docs/rfc.txt index ffd2f67..83cd029 100644 --- a/docs/rfc.txt +++ b/docs/rfc.txt @@ -34,9 +34,10 @@ Table of Contents 2.4.6. Message 2.4.7. Test 2.5. Sequential operations - 2.5.1. Client-Server connection initialisation - 2.5.2. Server-Server connection initialisation - 2.6. Server + 2.6. Client-Server connection initialisation + 2.7. Exchanging messages between servers + 2.7.1. Authentication + 2.7.2. Server-Server connection initialisation 1. Introduction @@ -167,7 +168,7 @@ Table of Contents +------+------------+------------+ | 0x03 | Handshake | SC | +------+------------+------------+ - | 0x04 | UserAuth | C | + | 0x04 | UserAuth | C | +------+------------+------------+ | 0x05 | Message | SC | +------+------------+------------+ @@ -201,8 +202,6 @@ Table of Contents +------+------------------------------------------------------------+ | 0x02 | Not found. User or channel cannot access user or | | | channel. | - +------+------------------------------------------------------------+ - | 0x03 | Server auth failed. Unknown name. | +------+------------------------------------------------------------+ Table 3 @@ -310,7 +309,7 @@ Table of Contents this specific operation (for example incoming message) cannot interrupt this process. -2.5.1. Client-Server connection initialisation +2.6. Client-Server connection initialisation +--------+ +--------+ | Client | | Server | @@ -322,20 +321,40 @@ Table of Contents | Send [Handshake] | +--------------------------->| | | - | +- If [ver_major] does not match server - | | protocol version close the connection + | +- If [ver_major] does not match + | | server protocol version close + | | the connection. | | - | Send [UserAuth] | + | Send [UserAuth] | +--------------------------->| | | | Send [Error 0x01] | - |<---------------------------+- If [username] or [password] does not match - | | and close the connection + |<---------------------------+- If [username] or [password] + | | does not match and close + | | the connection. | | | Send [Sucesss] | |<---------------------------+ -2.5.2. Server-Server connection initialisation +2.7. 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. + +2.7.1. 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. + +2.7.2. Server-Server connection initialisation +--------+ +--------+ | Server | | Server | @@ -347,17 +366,12 @@ Table of Contents | Send [Handshake] | +--------------------------->| | | - | +- If [ver_major] does not match server - | | protocol version close the connection + | +- If [ver_major] does not match + | | server protocol version close + | | the connection. | | | Send [ServerAuth] | +--------------------------->| | | - | Send [Error 0x03] | - |<---------------------------+- If [name] is not present in known public - | | keys list. - | | | Send [Sucesss] | |<---------------------------+ - -2.6. Server -- cgit v1.2.3
Table 9
Type