palm/palmdef/palm.proto

syntax = "proto3";

/*
  Palm Protocol Framework
    Palm is a dead-simple relaying protocol used to get data from A to B privately, securely and anonymously.
    These set of files provide a protobuf3 schema for parsing palm packets over-the-wire.

    Please note that after PalmR2CHandshakeFinishPacket, the entire datastream is encrypted with a stream cipher.
    It will need to be decrypted before it can be deserialized.

    There are four types of messages that can be sent:
    1. (C2R, R2C) Reflected, unencrypted. This type of message is unencrypted, and is communication between the client and the relay. This is called "reflection".\
    2. (EC2R, ER2C) Reflected, encrypted. This type of message is the same as unencrypted reflection, but is stream encrypted.
    3. (I2R, R2I) Tunneled, unencrypted. This type of message is unencrypted, and is passed through the relay. Although this packet is "unencrypted", it is still encrypted both ways via the relay connection - just the actual packet data is not encrypted and is readable by the relay.
    4. (EI2R, ER2I) Tunneled, encrypted. Similarly to unencrypted tunnel, this is passed through the relay. However, the actual packet data is also encrypted.

    Packets do NOT have sequential packet IDs. They are assigned in blocks.
    - 0x00-0x0f Internal packets. Reserved.
    - 0x10-0x2f Unencrypted reflection.
    - 0x30-0x4f Encrypted reflection.
    - 0x50-0x6f Unencrypted tunnel.
    - 0x70-0x8f Encrypted tunnel.
    - 0x90-0xdf Implementation-specific packets
    - 0xe0-0xff Internal packets. Reserved.

    Palm relays have static keys and must be trusted by clients.
    Relays are entered into clients via a palm url:

    palm[+<transport>]://[ip/domain]:[port]/[public key, hex-encoded]

    <transport> is the pluggable transport used to encapsulate the Palm protocol. Please note that it is outside the scope of Palm to verify that the transport of the client and server will match.
    If no transport is provided, `tcp` will be used, which will use a raw tcp connection. All clients and servers must support at least the `tcp` transport.

    For example, a relay using the "websocket" transport (required by all servers), on 1.2.3.4 port 5678, with the public key 957e7ccbebe84854d1cbcc59a4a2d993b9877e186745190722c78d72d6a9a218,
    would be entered into a client as follows:

    palm+websocket://1.2.3.4:5678/957e7ccbebe84854d1cbcc59a4a2d993b9877e186745190722c78d72d6a9a218

    The connection with a server is a relatively simple state machine.
    Client state machine:
    - Handshaking (after sending the handshake start)
    - WaitingHandshakeResponse (before receiving the handshake finish)
    - RelayConnected (after receiving the handshake finish)
    - WaitingForPeer (after sending channel wait)
    - Relayed (have an active relayed connection to the peer)
    - Disconnected (after being disconnected from the server)

    Relay state machine:
    - Handshaking (after receiving the handshake start)
    - WaitingRelayRequest (after sending the handshake finish)
    - WaitingForPeer (after sending channel not ready)
    - Relaying (after sending channel ready to client)
    - Disconnected (after the client has disconnected)

    Initiator (one of the peers, chosen randomly by the server) state machine:
    - Handshaking (after sending handshake start)
    - WaitingPeerRespponse (before receiving the handshake finish)
    - Tunneled (after receiving the handshake finish)
    - Disconnected (after the connection has been closed)

    Receiver (the other peer, chosen randomly by the server) state machine:
    - Handshaking (before receiving handshake start)
    - Tunneled (after sending handshake finish)
    - Disconnected (after the connection has been closed)


  Cryptography

    Palm uses a simple set of cryptographic functions.

    - BLAKE2s (32-byte digest) is used for hashing.
    - ChaCha20Poly1305 is used for authenticated encryption of data.

  Channel Identifiers and Keys

    The channel ID (channel_id, cid) and pre-shared master key (pmk) are very important values, used in almost all of the cryptography
    inside Palm. Given a user-friendly channel name channel_name, the two keys can be generated as follows:

    pmk = BLAKE2s(channel_name)
    channel_id = BLAKE2s(pmk)


 */

import "unencrypted_reflection.proto";
import "encrypted_reflection.proto";
import "unencrypted_tunnel.proto";
import "encrypted_tunnel.proto";

// The core message, used to serialize all other packets.
message PalmPacket {
  int32 packet_id = 1;      // What is the Packet ID of this packet?
  bytes packet_data = 2;    // Protobuf-encoded bytearray containing actual packet data. Might be encrypted.
}