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`