diff --git a/docs/TrinitrixBackendAPI.md b/docs/TrinitrixBackendAPI.md new file mode 100644 index 0000000..15d2de2 --- /dev/null +++ b/docs/TrinitrixBackendAPI.md @@ -0,0 +1,40 @@ +# Trinitrix Backend API (TriBA) + +## Basic concept + +The core starts a CBS as its child process and gives it as first Arg a base64 encoded UUID. +The CBS then connects to the local fs (or namespaced) socket. +After performing a handshake, which includes exchange of encryption keys, all communication +between core and CBS is encrypted (AES256-GCM-SIV) and serialized using [MessagePack](https://msgpack.org) + +## Packets + +Post-Handshake communication is structured in packets, which have the following structure in their raw form: + +| Size (bytes) | Type | Content | +|--------------|-------------------|--------------------------------------------------------------------| +| 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: + +| 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) | + +## Handshake + +The handshaking process after connecting to the socket looks as follows: + +1. The CBS sends its ID as 16 raw bytes. +2. When the ID is not known to the core, it aborts the handshaking process by closing the connection. +3. The core sends its Public Key for this connection. Again just 32 raw bytes. +4. The CBS sends its Public Key for this connection. +5. The core sends a 12 byte nonce value. +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