forked from trinitrix/core
61 lines
3.4 KiB
Markdown
61 lines
3.4 KiB
Markdown
# 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.
|
|
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 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. |
|
|
| - | `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
|
|
|
|
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 `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` |