GERTe Relay Protocol

Decentralized TCP Overlay Network

Forewords

GERTe operates over TCP for maximum compatibility and reliability.

The software known as GEDS relays data and commands across the network.
GEDS servers are known as nodes. Externally they may be referred to as peers.

Various APIs allow client access to the network. These are typically called GERTe APIs.
These clients are sometimes externally referred to as gateways.
Gateways typically provide NAT-like access between GERTi and GERTe.

GERTe uses binary encoded packets to minimize packet size and thus latency.

Binary Structures

A few binary structures occur repeatedly throughout GERTe. They will be defined here and referenced by name later.

GERTe Address

GERT Addresses take two forms, incomplete and complete.
Partial addresses are 3 bytes. Complete addresses are 6 bytes.

Addresses are two 12-bit integers packed into the 3 byte structures.

Complete addresses consist of two incomplete addresses, an external and an internal.
The internal is usually used by GERTi and passed to it by the gateway.

Data String

Data strings are variable length strings of arbitrary encoding and content.
Data strings lengths are determined elsewhere in the packet, there is no delimiter. This enables full 256 possible "characters."

ECDSA Signature

EC-Signatures are DER-encoded ECDSA signatures generated by various libraries.
Signatures have no set length, they are prefixed by an 8-bit length integer.

Version Pair

Version pairs are mostly seen within handshakes, but they can also be seen in queries.
They consist of two 8-bit integers, the first being major version, the second being minor.

Version pairs refer to the protocol version.
Depending on the software developer's versioning system, this may not be the software's version.

Errors

There are a list of errors within GERTe. They are byte-encoded, i.e. error 1 is 0x01

0. Version error, usually unsupported version.
1. Unknown address.
2. Unknown internal error.

Handshake (Generic)

Regardless of which device is running what software, a generic handshake occurs.

This handshake consists of the connecting device sending a version pair.
The receiving device then either sends a version pair, or a 0, 0 pair with the specified error.

Gateways

Under the current system, clients communicate using a simplified version of the overall protocol.
The simplified version consists only of data packets back and forth with no commands.

Handshake

The client has an extended handshake, consisting of sending its own address after the version pair.
This allows the node to find the key and reject the connection if it cannot load the key.

Note: The address must be sent immediately, the node will not respond without it.

Data Packet

This data packet is shared with the node's relay packet, since the node cannot modify it.

The data packet consists of several parts.

• 16-bit length integer
• Complete source address
• Complete destination address
• Data byte of length bytes
• 64-bit timestamp (seconds since UTC epoch)
• ECDSA Signature

The entire data packet outside the signature (and its the 8-bit length) is signed by the signature.
Nodes should reject all packets with a timestamp >60 seconds ago (and optionally sooner.)
Nodes must reject all packets from a source external address not matching the identity.
Nodes may verify the signature. If a node verifies the signature, it must reject failed verifications.

Node to Node

Nodes use a more complex protocol to enable better cooperation.

This complex protocol features commands to specify which packet is being sent.

Commands

Commands are byte-encoded, i.e. command 1 is 0x01

0. Query (Can you contact this address?)
1. Present (I can contact this address.)
2. Absent (I can not contact this address.)
3. Relay

Query, Present, Absent

Nodes determine routes using Query packets and Present and Absent response packets.

Query packets consist only of the desired incomplete address.
Absent packets also follow this format.

Present packets consist of the incomplete address, the version pair of the client, and a boolean.
The boolean indicates if the responding node is directly connected to the client or through another node.

Relay

Data packets cannot be modified by nodes without invalidating the signature.
For this reason it is best if nodes pass the entire data packet unmodified.

This, however, makes relay packets exceedingly simple, they are just the original data packet.

Cryptography

The GERTe protocol supports many more features. Unfortunately they are currently unimplemented in reference APIs.
For this reason this document will currently omit them incase they change substantially.