trinitrix/core
trinitrix
/
core
Archived
5
4
Fork 2
Code Issues 8 Pull Requests Packages Projects Releases Wiki Activity

docs: updated the TriBA docs to match the response update

This commit is contained in:
antifallobst 2024-05-21 05:00:37 +02:00
parent fc8efe5060
commit 916ea87537
Signed by: antifallobst
GPG Key ID: 2B4F402172791BAF
1 changed files with 27 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
docs/TrinitrixBackendAPI.md
View File

@ -1,5 +1,7 @@
# Trinitrix Backend API (TriBA)
**Disclaimer:** These docs are WIP and going to receive a lot of improvement.
## Basic concept
The core starts a CBS as its child process and gives it as first Arg a base64 encoded UUID.
@ -16,12 +18,29 @@ Post-Handshake communication is structured in packets, which have the following
| 4 | uint32 | The size of the payload. |
| - | encrypted payload | The AES-GCM-SIV encrypted MessagePack serialization of the packet. |
A decrypted and deserialized packet looks like this:
A decrypted and deserialized payload contains either a response or a request.
A request looks as follows:
| Size | Name | Type | Content |
|------|--------|--------|-------------------------------------------------------------------------------------------------------------------|
| 8 | `id` | uint64 | The ID of _this_ packet. Is expected to be an incrementing counter. |
| - | `body` | enum | The actual packet date. (this will be better documented, as soon, as I dive into the mPack serialization details) |
| 8 | `id` | uint64 | The ID of _this_ packet. |
| - | `body` | enum | The actual packet data. (this will be better documented, as soon, as I dive into the mPack serialization details) |
A response looks like this:
| Size | Name | Type | Content |
|------|--------|--------|-------------------------------------------------------|
| 8 | `id` | uint64 | The ID of _this_ packet. |
| 8 | `req` | uint64 | The ID of the request packet this response refers to. |
| - | `body` | enum | The actual packet data. |
**Every request packet, that is sent over the socket, has to get a linked response packet.**
### IDs
Packet IDs are expected to be an incremental counter.
There is no difference between requests and responses originating from the same socket side when it comes to IDs.
So both - requests and responses - should share the same counter.
## Handshake
@ -35,6 +54,8 @@ The handshaking process after connecting to the socket looks as follows:
6. __Connection Upgrade:__ From this point on, all communication is structured by packets.
The packet encryption key is calculated using x25519 Diffie-Hellman and the previously exchanged keys.
The nonce from step 5 will be used as nonce for all packets.
7. The CBS sends the `HandshakeUpgradeConnection` packet.
8. (In here there is going to happen API version information exchange etc.)
9. The Core responds with `HandshakeSuccess`
7. The CBS sends the `Request::HandshakeUpgradeConnection` packet.
8. The core responds with `Response::Success`.
9. (In here there is going to happen API version information exchange etc.)
10. The Core sends a `Request::HandshakeSuccess`
11. The CBS responds with `Response::Succcess`