From 916ea87537e2a46950160a69d90ebd2dedafc060 Mon Sep 17 00:00:00 2001 From: antifallobst Date: Tue, 21 May 2024 05:00:37 +0200 Subject: [PATCH] docs: updated the TriBA docs to match the response update --- docs/TrinitrixBackendAPI.md | 33 +++++++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 6 deletions(-) diff --git a/docs/TrinitrixBackendAPI.md b/docs/TrinitrixBackendAPI.md index 15d2de2..8a5a1dc 100644 --- a/docs/TrinitrixBackendAPI.md +++ b/docs/TrinitrixBackendAPI.md @@ -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` \ No newline at end of file +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` \ No newline at end of file