forked from trinitrix/core
40 lines
2.4 KiB
Markdown
40 lines
2.4 KiB
Markdown
|
# 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`
|