From: Felix Fietkau <nbd@nbd.name>
Date: Thu, 23 Jun 2022 11:09:48 +0000 (+0200)
Subject: add some documentation about the PEX protocol
X-Git-Url: http://git.openwrt.org/?a=commitdiff_plain;h=2e2171edeacf81c29feba9525c5413e8a27bc8e2;p=project%2Funetd.git

add some documentation about the PEX protocol

Signed-off-by: Felix Fietkau <nbd@nbd.name>
---

diff --git a/PEX.md b/PEX.md
new file mode 100644
index 0000000..4d42ad4
--- /dev/null
+++ b/PEX.md
@@ -0,0 +1,78 @@
+
+# PEX - Peer Endpoint eXchange protocol
+
+## Header:
+
+	struct pex_hdr {
+	    uint8_t version;
+	    uint8_t opcode;
+	    uint16_t len;
+	    uint8_t id[8];
+	};
+
+- version: always 0 for now
+- opcode: message type
+- len: payload length
+- id: local peer id
+
+All multi-byte integer fields are in big-endian byte order.
+Peer identifiers contain the first 8 bytes of the public key
+
+## Message types
+
+### opcode=0: PEX_MSG_HELLO
+
+Payload (single item):
+
+	struct pex_hello {
+	    uint16_t flags;
+	    uint8_t local_addr[16];
+	};
+
+- local_addr: Local IPv4 or IPv6 address used for connecting to the remote endpoint
+- flags:
+Bit 0: local_addr is an IPv6 address
+
+Sent after any successful handshake.
+
+### opcode=1: PEX_MSG_NOTIFY_PEERS
+
+Used to send information about one or more peers, either proactively, or as a response to PEX_MSG_QUERY
+
+Payload (multiple):
+
+	struct pex_peer_endpoint {
+	    uint16_t flags;
+	    uint16_t port;
+	    uint8_t peer_id[PEX_ID_LEN];
+	    uint8_t addr[16];
+	};
+
+- port: endpoint port
+- addr: IPv4 or IPv6 endpoint address
+- peer_id: peer ID
+- flags:
+Bit 0: addr is an IPv6 address
+Bit 1: addr refers to the local network address of the peer
+
+### opcode=2: PEX_MSG_QUERY
+
+Used to ask for the endpoint address of one or more peers. Expects a PEX_MSG_NOTIFY_PEERS response, but only if there is known data about any of the queried peers.
+
+Payload (multiple):
+
+	uint8_t peer_id[8];
+
+For any peer in the payload list that has a known endpoint address, compare the IP address against the endpoint address of the sender of this message.
+If the IP address matches, send back the local address of the peer (from the PEX_MSG_HELLO message) instead of the discovered wireguard endpoint address. This helps with establishing a direct connection through double-NAT.
+
+### opcode=3: PEX_MSG_PING
+
+Used to ping a peer (to keep the connection alive).
+No payload.
+
+### opcode=4: PEX_MSG_PONG
+
+Response to PEX_MSG_PING.
+No payload.
+