PEX.md

   1
   2 # PEX - Peer Endpoint eXchange protocol
   3
   4 ## Header:
   5
   6         struct pex_hdr {
   7             uint8_t version;
   8             uint8_t opcode;
   9             uint16_t len;
  10             uint8_t id[8];
  11         };
  12
  13 - version: always 0 for now
  14 - opcode: message type
  15 - len: payload length
  16 - id: local peer id
  17
  18 All multi-byte integer fields are in big-endian byte order.
  19 Peer identifiers contain the first 8 bytes of the public key
  20
  21 ## Message types
  22
  23 ### opcode=0: PEX_MSG_HELLO
  24
  25 Payload (single item):
  26
  27         struct pex_hello {
  28             uint16_t flags;
  29             uint8_t local_addr[16];
  30         };
  31
  32 - local_addr: Local IPv4 or IPv6 address used for connecting to the remote endpoint
  33 - flags:
  34 Bit 0: local_addr is an IPv6 address
  35
  36 Sent after any successful handshake.
  37
  38 ### opcode=1: PEX_MSG_NOTIFY_PEERS
  39
  40 Used to send information about one or more peers, either proactively, or as a response to PEX_MSG_QUERY
  41
  42 Payload (multiple):
  43
  44         struct pex_peer_endpoint {
  45             uint16_t flags;
  46             uint16_t port;
  47             uint8_t peer_id[PEX_ID_LEN];
  48             uint8_t addr[16];
  49         };
  50
  51 - port: endpoint port
  52 - addr: IPv4 or IPv6 endpoint address
  53 - peer_id: peer ID
  54 - flags:
  55 Bit 0: addr is an IPv6 address
  56 Bit 1: addr refers to the local network address of the peer
  57
  58 ### opcode=2: PEX_MSG_QUERY
  59
  60 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.
  61
  62 Payload (multiple):
  63
  64         uint8_t peer_id[8];
  65
  66 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.
  67 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.
  68
  69 ### opcode=3: PEX_MSG_PING
  70
  71 Used to ping a peer (to keep the connection alive).
  72 No payload.
  73
  74 ### opcode=4: PEX_MSG_PONG
  75
  76 Response to PEX_MSG_PING.
  77 No payload.
  78