2 # PEX - Peer Endpoint eXchange protocol
13 - version: always 0 for now
14 - opcode: message type
18 All multi-byte integer fields are in big-endian byte order.
19 Peer identifiers contain the first 8 bytes of the public key
23 ### opcode=0: PEX_MSG_HELLO
25 Payload (single item):
29 uint8_t local_addr[16];
32 - local_addr: Local IPv4 or IPv6 address used for connecting to the remote endpoint
34 Bit 0: local_addr is an IPv6 address
36 Sent after any successful handshake.
38 ### opcode=1: PEX_MSG_NOTIFY_PEERS
40 Used to send information about one or more peers, either proactively, or as a response to PEX_MSG_QUERY
44 struct pex_peer_endpoint {
47 uint8_t peer_id[PEX_ID_LEN];
52 - addr: IPv4 or IPv6 endpoint address
55 Bit 0: addr is an IPv6 address
56 Bit 1: addr refers to the local network address of the peer
58 ### opcode=2: PEX_MSG_QUERY
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.
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.
69 ### opcode=3: PEX_MSG_PING
71 Used to ping a peer (to keep the connection alive).
74 ### opcode=4: PEX_MSG_PONG
76 Response to PEX_MSG_PING.
79 ## Unencrypted messages (outside of the tunnel)
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:
89 - nonce: nonce for id hash
90 - auth_id: first 8 bytes of the auth public key
92 In these messages, pex_hdr::id is XORed with siphash(req_id || req_id, auth_key)
94 ### opcode=5: PEX_MSG_UPDATE_REQUEST
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
100 struct pex_update_request {
101 uint64_t cur_version;
105 - cur_version: latest version of the network data that the sender already has
106 - req_id: request id copied to response messages
108 ### opcode=6: PEX_MSG_UPDATE_RESPONSE
110 Used to send updated signed network data to a peer
113 struct pex_update_response {
119 followed by the first chunk of network data.
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
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.
129 - e_key_priv: private key belonging to e_key
130 - peer_key: public key belonging to the receiver (from the network data)
132 ### opcode=7: PEX_MSG_UPDATE_RESPONSE_DATA
134 Continuation of PEX_MSG_UPDATE_RESPONSE network data
137 struct pex_update_response_data {
142 followed by encrypted network data
144 ### opcode=8: PEX_MSG_UPDATE_RESPONSE_NO_DATA
146 Indicates that the network data with the timestamp given in PEX_MSG_UPDATE_REQUEST
151 struct pex_update_response_no_data {
153 uint64_t cur_version;
156 - req_id: request id of the PEX_MSG_UPDATE_REQUEST message
157 - cur_version: latest version of the network data