unet-cli: strip initial newline in usage message

[project/unetd.git] / PEX.md

diff --git a/PEX.md b/PEX.md
index 4d42ad4944c77135baeb736ce811d0e7b3d083c0..241c6be9af18e477a471ab45f3d0b030e950efa5 100644 (file)
--- a/PEX.md
+++ b/PEX.md
@@ -76,3 +76,82 @@ No payload.
 Response to PEX_MSG_PING.
 No payload.
 
+## Unencrypted messages (outside of the tunnel)
+
+These are only supported for networks using signed network data that can be updated dynamically.
+The struct pex_hdr header is followed by a second header:
+
+       struct pex_ext_hdr {
+               uint64_t nonce;
+               uint8_t auth_id[8];
+       };
+
+- nonce: nonce for id hash
+- auth_id: first 8 bytes of the auth public key
+
+In these messages, pex_hdr::id is XORed with siphash(req_id || req_id, auth_key)
+
+### opcode=5: PEX_MSG_UPDATE_REQUEST
+
+This message can be used outside of the wireguard tunnel in order to request signed network data
+It is used to ask a peer for the latest signed network data
+
+Payload:
+       struct pex_update_request {
+               uint64_t cur_version;
+               uint32_t req_id;
+       };
+
+- cur_version: latest version of the network data that the sender already has
+- req_id: request id copied to response messages
+
+### opcode=6: PEX_MSG_UPDATE_RESPONSE
+
+Used to send updated signed network data to a peer
+
+Payload:
+       struct pex_update_response {
+               uint64_t req_id;
+               uint32_t data_len;
+               uint8_t e_key[32];
+       };
+
+followed by the first chunk of network data.
+
+- req_id: request id of the PEX_MSG_UPDATE_REQUEST message
+- data_len: total length of the network data
+- e_key: ephemeral curve25519 public key
+
+The network data is chacha20 encrypted with the following key:
+       DH(e_key_priv, peer_key)
+And using req_id as nonce.
+
+- e_key_priv: private key belonging to e_key
+- peer_key: public key belonging to the receiver (from the network data)
+
+### opcode=7: PEX_MSG_UPDATE_RESPONSE_DATA
+
+Continuation of PEX_MSG_UPDATE_RESPONSE network data
+
+Payload:
+       struct pex_update_response_data {
+               uint64_t req_id;
+               uint32_t offset;
+       };
+
+followed by encrypted network data
+
+### opcode=8: PEX_MSG_UPDATE_RESPONSE_NO_DATA
+
+Indicates that the network data with the timestamp given in PEX_MSG_UPDATE_REQUEST
+is up to date
+
+Payload:
+
+       struct pex_update_response_no_data {
+               uint64_t req_id;
+               uint64_t cur_version;
+       };
+
+- req_id: request id of the PEX_MSG_UPDATE_REQUEST message
+- cur_version: latest version of the network data