forked from trinitrix/core
1
0
Fork 0
core/docs/TrinitrixBackendAPI.md

3.4 KiB

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

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