trinitrix/core
trinitrix
/
core
Archived
5
4
Fork 2
Code Issues 8 Pull Requests Packages Projects Releases Wiki Activity

docs: documented the TriBA handshaking process

This commit is contained in:
antifallobst 2024-05-14 14:45:13 +02:00
parent 64d5bdd9c5
commit 042da55f28
Signed by: antifallobst
GPG Key ID: 2B4F402172791BAF
1 changed files with 40 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
docs/TrinitrixBackendAPI.md Normal file
View File

@ -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`