EntglDb Peer-to-Peer Communication and Security Protocol

Introduction EntglDb requires a robust protocol to enable multiple nodes (peers) to discover each other on a local network, establish a secure communication channel, and synchronize data efficiently. This specification details the wire format, discovery beacons, handshake procedures, and security requirements to ensure interoperability between different EntglDb client implementations.

Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Discovery Protocol Nodes automatically discover each other using UDP broadcasts.

Beacon Constants

Port: 25000
Interval: 5000 ms
Transport: UDP Broadcast/Multicast

Beacon Payload The payload MUST be a UTF-8 encoded JSON string adhering to the following structure: { "node_id": "UUID-STRING", "tcp_port": 25000 } Receiving nodes MUST ignore beacons originating from their own node_id.

TCP Connection and Framing Upon discovery, a node initiates a TCP connection to the advertised IP and tcp_port.

Frame Structure All messages sent over the TCP stream MUST adhere to the following length-prefixed format. All integers are Little Endian. +----------------+--------------+-----------------+------------------+ | Length (4 bytes)| Type (1 byte)| Compress (1 byte)| Payload (N bytes)| +----------------+--------------+-----------------+------------------+

Length: 32-bit signed integer representing the size of the Payload only. It does NOT include the header size (6 bytes).
Type: 1-byte enum identifying the message type.
Compression: 1-byte flag. 0x00 = None, 0x01 = Brotli.
Payload: The serialized Protocol Buffer message.

Message Types The Type byte corresponds to the following values:

ID	Name	Description
1	HandshakeReq	Connection connection request
2	HandshakeRes	Connection response
3	GetClockReq	Request current HLC
4	ClockRes	HLC response
5	PullChangesReq	Request Oplog diff
6	ChangeSetRes	Send batch of changes
7	PushChangesReq	Proactive changes push
8	AckRes	Receipt confirmation
9	SecureEnv	Encrypted envelope

Security and Handshake Security is mandatory. The protocol enforces an encrypted channel using ECDH for key exchange and AES-GCM for confidentiality and integrity.

Phase 1: ECDH Key Exchange Before any Protobuf messages are exchanged, a raw key exchange occurs:

Initiator sends: 4-byte Length + Public Key (NIST P-256 SubjectPublicKeyInfo).
Responder sends: 4-byte Length + Public Key (NIST P-256 SubjectPublicKeyInfo).

Both parties compute the Shared Secret. Session keys are derived using a simplified HKDF-like scheme:

Key1 = SHA256(Secret || 0x00)
Key2 = SHA256(Secret || 0x01)

The Initiator uses Key1 for encryption and Key2 for decryption. The Responder uses Key2 for encryption and Key1 for decryption.

Phase 2: Secure Envelope After key exchange, ALL subsequent frames MUST have Type = 9 (SecureEnv). The payload of a SecureEnv message is a Protobuf SecureEnvelope: message SecureEnvelope { bytes ciphertext = 1; bytes nonce = 2; // 12 bytes bytes auth_tag = 3; // 16 bytes } The plaintext inside the encrypted ciphertext contains the inner wire format: [Type (1 byte)] [Compression (1 byte)] [Inner Payload]

Security Considerations This protocol relies on the strength of NIST P-256 and AES-256-GCM. Implementers MUST ensure secure random number generation for ephemeral keys and nonces. Authentication: While the current handshake encrypts traffic, robust node authentication relies on the auth_token field in the HandshakeReq. Implementations SHOULD verify this token against a trusted authority or ACL. Man-in-the-Middle (MitM): The current ECDH exchange is anonymous. To prevent MitM attacks, future versions MAY include signing of the ephemeral public keys using a long-term identity key.

IANA Considerations This document registers the following UDP/TCP port for EntglDb Discovery and Synchronization:

Port: 25000
Use: EntglDb Beacon (UDP) and Sync Protocol (TCP)