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
  79 ## Unencrypted messages (outside of the tunnel)
  80
  81 These are only supported for networks using signed network data that can be updated dynamically.
  82 The struct pex_hdr header is followed by a second header:
  83
  84         struct pex_ext_hdr {
  85                 uint64_t nonce;
  86                 uint8_t auth_id[8];
  87         };
  88
  89 - nonce: nonce for id hash
  90 - auth_id: first 8 bytes of the auth public key
  91
  92 In these messages, pex_hdr::id is XORed with siphash(req_id || req_id, auth_key)
  93
  94 ### opcode=5: PEX_MSG_UPDATE_REQUEST
  95
  96 This message can be used outside of the wireguard tunnel in order to request signed network data
  97 It is used to ask a peer for the latest signed network data
  98
  99 Payload:
 100         struct pex_update_request {
 101                 uint64_t cur_version;
 102                 uint32_t req_id;
 103         };
 104
 105 - cur_version: latest version of the network data that the sender already has
 106 - req_id: request id copied to response messages
 107
 108 ### opcode=6: PEX_MSG_UPDATE_RESPONSE
 109
 110 Used to send updated signed network data to a peer
 111
 112 Payload:
 113         struct pex_update_response {
 114                 uint64_t req_id;
 115                 uint32_t data_len;
 116                 uint8_t e_key[32];
 117         };
 118
 119 followed by the first chunk of network data.
 120
 121 - req_id: request id of the PEX_MSG_UPDATE_REQUEST message
 122 - data_len: total length of the network data
 123 - e_key: ephemeral curve25519 public key
 124
 125 The network data is chacha20 encrypted with the following key:
 126         DH(e_key_priv, peer_key)
 127 And using req_id as nonce.
 128
 129 - e_key_priv: private key belonging to e_key
 130 - peer_key: public key belonging to the receiver (from the network data)
 131
 132 ### opcode=7: PEX_MSG_UPDATE_RESPONSE_DATA
 133
 134 Continuation of PEX_MSG_UPDATE_RESPONSE network data
 135
 136 Payload:
 137         struct pex_update_response_data {
 138                 uint64_t req_id;
 139                 uint32_t offset;
 140         };
 141
 142 followed by encrypted network data
 143
 144 ### opcode=8: PEX_MSG_UPDATE_RESPONSE_NO_DATA
 145
 146 Indicates that the network data with the timestamp given in PEX_MSG_UPDATE_REQUEST
 147 is up to date
 148
 149 Payload:
 150
 151         struct pex_update_response_no_data {
 152                 uint64_t req_id;
 153                 uint64_t cur_version;
 154         };
 155
 156 - req_id: request id of the PEX_MSG_UPDATE_REQUEST message
 157 - cur_version: latest version of the network data