From 355bc0febeee5688c2dea33d1530cab68ef720a9 Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Sat, 24 Feb 2024 19:54:39 -0500 Subject: [PATCH 1/8] Create peer-exchange.md --- waku/standards/core/34/peer-exchange.md | 168 ++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 waku/standards/core/34/peer-exchange.md diff --git a/waku/standards/core/34/peer-exchange.md b/waku/standards/core/34/peer-exchange.md new file mode 100644 index 000000000..7b77f3e99 --- /dev/null +++ b/waku/standards/core/34/peer-exchange.md @@ -0,0 +1,168 @@ +--- +title: WAKU2-PEER-EXCHANGE +name: Waku v2 Peer Exchange +category: Standards Track +tags: waku/core-protocol +editor: Daniel Kaiser +contributors: +--- + +## Abstract + +This document specifies a simple request-response peer exchange protocol. +Responders send information about a requested number of peers. +The main purpose of this protocol is providing resource restricted devices with peers. + +**Protocol identifier**: /vac/waku/peer-exchange/2.0.0-alpha1 + +## Background and Motivation + +It may not be feasible on resource restricted devices to take part in distributed random sampling ambient peer discovery protocols such as [33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/). +The Waku peer discovery protocol specified in this document allows resource restricted devices to request a list of peers from a service node. +Network parameters necessary to connect to this service node COULD be learned from a static bootstrapping method or using [EIP-1459: Node Discovery via DNS](https://eips.ethereum.org/EIPS/eip-1459). +The advantage of using Waku peer exchange to discover new peers over using a static peer list or DNS discovery is a more even load distribution. +If a lot of (resource restricted) nodes would use the same service nodes as relay or store nodes, the load on these would be very high. +Heavily used static nodes also add a centralized element. Downtime of such a node might significantly impact the network. + +However, the resource efficiency of this protocol comes at an anonymity cost, which is explained in the [Security/Privacy Considerations](#securityprivacy-considerations) section. +This protocol SHOULD only be used if [33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/) is infeasible. + +## Theory and Protocol Semantics + +The peer exchange protocol specified in this document is a simple request-response protocol. +As Figure 1 illustrates, the requesting node sends a request to a peer, which acts as the responder. +The responder replies with a list of ENRs as specified in [WAKU2-ENR](../enr.md). +The [multiaddresses](https://docs.libp2p.io/concepts/addressing/) used to connect to the respective peers can be extracted from the ENRs. + +![Figure 1: The responder provides a list of ENRs to the requester. These ENRs contain the information necessary for connecting to the respective peers.](../../images/protocol.svg) + +In order to protect its anonymity, the responder MUST NOT provide peers from its actively used peer list as this opens pathways to *Neighbourhood Surveillance* attacks, as described in the +[Security/Privacy Considerations Section](#securityprivacy-considerations). +The responder SHOULD provide a set of peers that has been retrieved using ambient peer discovery methods supporting random sampling, e.g. [33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/). +This both protects the responder's anonymity as well as helps distributing load. + +To allow for fast responses, responders SHOULD retrieve peers unsolicited (before receiving a query) +and maintain a queue of peers for the purpose of providing them in peer exchange responses. +To get the best anonymity properties with respect to response peer sets, responders SHOULD use each of these peers only once. + +To save bandwidth, and as a trade off to anonymity, +responders MAY maintain a larger cache of exchange peers and randomly sample response sets from this local cache. +The size of the cache SHOULD be large enough to allow randomly sampling peer sets that (on average) do not overlap too much. +The responder SHOULD periodically replace the oldest peers in the cache. +This document provides recommended choices for the cache size in the [Implementation Suggestions Section](#implementation-suggestions). + +Requesters, in the context of the specified peer exchange protocol, SHOULD be resource restricted devices. +While any node could technically act as a requester, using the peer exchange protocol comes with two drawbacks: + +* reducing [anonymity](#securityprivacy-considerations) +* causing load on responder nodes + +## Wire Format Specification + +```protobuf +syntax = "proto3"; + +message PeerInfo { + bytes enr = 1; +} + +message PeerExchangeQuery { + uint64 num_peers = 1; +} + +message PeerExchangeResponse { + repeated PeerInfo peer_infos = 1; +} + +message PeerExchangeRPC { + PeerExchangeQuery query = 1; + PeerExchangeResponse response = 2; +} + +``` + +The `enr` field contains a Waku ENR as specified in [WAKU2-ENR](../enr.md). + +Requesters send a `PeerExchangeQuery` to a peer. +Responders SHOULD include a maximum of `num_peers` `PeerInfo` instances into a response. +Responders send a `PeerExchangeResponse` to requesters containing a list of `PeerInfo` instances, which in turn hold an ENR. + +## Implementation Suggestions + +### Discovery Interface + +Implementations can implement the libp2p discovery interface (e.g. [nim](https://github.com/status-im/nim-libp2p/issues/140), [javascript](https://github.com/libp2p/js-libp2p-interfaces/tree/master/packages/interface-peer-discovery)). + +### Exchange Peer Cache Size + +The size of the (optional) exchange peer cache discussed in [Theory and Protocol Semantics](#theory-and-protocol-semantics) +depends on the average number of requested peers, which is expected to be the outbound degree of the underlying +[libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md) mesh network. +The recommended value for this outbound degree is 6 (see parameter `D` in [29/WAKU2-CONFIG](https://rfc.vac.dev/spec/29/)). +It is recommended for the cache to hold at least 10 times as many peers (60). + +The recommended cache size also depends on the number of requesters a responder is expected to serve within a *refresh cycle*. +A refresh cycle is the time interval in which all peers in the cache are expected to be replaced. +If the number of requests expected per refresh cycle exceeds 600 (10 times the above recommended 60), +it is recommended to increase the cache size to at least a tenth of that number. + +We will investigate peer exchange cache sizes and refresh strategies, +and provide suggestions based on that in future versions (draft, stable) of this document. + +## Security/Privacy/Anonymity Considerations + +The peer exchange protocol specified in this document comes with anonymity and security implications. +We differentiate these implications into the requester and responder side, respectively. + +### Requester + +With a simple peer exchange protocol, the requester is inherently susceptible to both *neighbourhood surveillance* and *controlled neighbourhood* attacks. + +To mount a *neighbourhood surveillance* attack, an attacker has to connect to the peers of the victim node. +The peer exchange protocol allows a malicious responder to easily get into this position. +The responder connects to a set of peers and simply returns this set of peers to the requester. + +The peer exchange protocol also makes it much easier to get into the position required for the *controlled neighbourhood* attack: +A malicious responder provides controlled peers in the response peer list. + +More on these attacks may be found in our [research log article](https://vac.dev/wakuv2-relay-anon). + +As a weak mitigation the requester MAY ask several peers and select a subset of the returned peers. + +### Responder + +Responders that answer with active mesh peers are more vulnerable to a *neighbourhood surveillance* attack. +Responding with the set of active mesh peers allows a malicious requester to get into the required position more easily. +It takes away the first hurdle of the *neighbourhood surveillance* attack: The attacker knows which peers to try to connect to. +This increased vulnerability can be avoided by only responding with randomly sampled sets of peers, e.g. by requesting a random peer set via [33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/). +(As stated in the [Theory and Protocol Semantics Section](#theory-and-protocol-semantics), +these peer sets SHOULD be retrieved unsolicitedly before receiving requests to achieve faster response times.) + +Responders are also susceptible to amplification DoS attacks. +Requesters send a simple message request which causes responders to engage in ambient peer discovery to retrieve a new random peer set. +As a mitigation, responders MAY feature a `seen cache` for requests and only answer once per time interval. +The exchange-peer cache discussed in [Theory and Protocol Semantics Section](#theory-and-protocol-semantics) also provides mitigation. +Still, frequent queries can tigger the refresh cycle more often. The `seen cache` MAY be used in conjunction to provide additional mitigation. + +### Further Considerations + +The response field contains ENRs as specified in [WAKU2-ENR](../enr.md). +While ENRs contain signatures, they do not violate the [Waku relay no-sign policy](https://rfc.vac.dev/spec/11/#signature-policy)), +because they are part of the discovery domain and are not propagated in the relay domain. +However, there might still be some form of leakage: +ENRs could be used to track peers and facilitate linking attacks. +We will investigate this further in our Waku anonymity analysis. + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). + +## References + +* [33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/) +* [WAKU2-ENR](../enr.md) +* [multiaddress](https://docs.libp2p.io/concepts/addressing/) +* [libp2p discovery interface](https://github.com/status-im/nim-libp2p/issues/140) +* [libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md) +* [29/WAKU2-CONFIG](https://rfc.vac.dev/spec/29/) +* [Waku relay anonymity](https://vac.dev/wakuv2-relay-anon) From 49d8578b8467d167e05d48cfe058279bccdac26d Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Thu, 21 Mar 2024 16:06:30 -0400 Subject: [PATCH 2/8] Update peer-exchange.md --- waku/standards/core/34/peer-exchange.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/waku/standards/core/34/peer-exchange.md b/waku/standards/core/34/peer-exchange.md index 7b77f3e99..993e79b8a 100644 --- a/waku/standards/core/34/peer-exchange.md +++ b/waku/standards/core/34/peer-exchange.md @@ -1,10 +1,13 @@ --- -title: WAKU2-PEER-EXCHANGE +slug: 34 +title: 34/WAKU2-PEER-EXCHANGE name: Waku v2 Peer Exchange +status: draft category: Standards Track tags: waku/core-protocol -editor: Daniel Kaiser +editor: Hanno Cornelius contributors: +- Daniel Kaiser --- ## Abstract @@ -13,11 +16,13 @@ This document specifies a simple request-response peer exchange protocol. Responders send information about a requested number of peers. The main purpose of this protocol is providing resource restricted devices with peers. -**Protocol identifier**: /vac/waku/peer-exchange/2.0.0-alpha1 +***Protocol Identifier*** + + /vac/waku/peer-exchange/2.0.0-alpha1 ## Background and Motivation -It may not be feasible on resource restricted devices to take part in distributed random sampling ambient peer discovery protocols such as [33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/). +It may not be feasible on resource restricted devices to take part in distributed random sampling ambient peer discovery protocols such as [33/WAKU2-DISCV5](../33/discv5.md). The Waku peer discovery protocol specified in this document allows resource restricted devices to request a list of peers from a service node. Network parameters necessary to connect to this service node COULD be learned from a static bootstrapping method or using [EIP-1459: Node Discovery via DNS](https://eips.ethereum.org/EIPS/eip-1459). The advantage of using Waku peer exchange to discover new peers over using a static peer list or DNS discovery is a more even load distribution. @@ -25,7 +30,7 @@ If a lot of (resource restricted) nodes would use the same service nodes as rela Heavily used static nodes also add a centralized element. Downtime of such a node might significantly impact the network. However, the resource efficiency of this protocol comes at an anonymity cost, which is explained in the [Security/Privacy Considerations](#securityprivacy-considerations) section. -This protocol SHOULD only be used if [33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/) is infeasible. +This protocol SHOULD only be used if [33/WAKU2-DISCV5](../33/discv5.md) is infeasible. ## Theory and Protocol Semantics @@ -38,7 +43,7 @@ The [multiaddresses](https://docs.libp2p.io/concepts/addressing/) used to connec In order to protect its anonymity, the responder MUST NOT provide peers from its actively used peer list as this opens pathways to *Neighbourhood Surveillance* attacks, as described in the [Security/Privacy Considerations Section](#securityprivacy-considerations). -The responder SHOULD provide a set of peers that has been retrieved using ambient peer discovery methods supporting random sampling, e.g. [33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/). +The responder SHOULD provide a set of peers that has been retrieved using ambient peer discovery methods supporting random sampling, e.g. [33/WAKU2-DISCV5](../33/discv5.md). This both protects the responder's anonymity as well as helps distributing load. To allow for fast responses, responders SHOULD retrieve peers unsolicited (before receiving a query) @@ -134,7 +139,7 @@ As a weak mitigation the requester MAY ask several peers and select a subset of Responders that answer with active mesh peers are more vulnerable to a *neighbourhood surveillance* attack. Responding with the set of active mesh peers allows a malicious requester to get into the required position more easily. It takes away the first hurdle of the *neighbourhood surveillance* attack: The attacker knows which peers to try to connect to. -This increased vulnerability can be avoided by only responding with randomly sampled sets of peers, e.g. by requesting a random peer set via [33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/). +This increased vulnerability can be avoided by only responding with randomly sampled sets of peers, e.g. by requesting a random peer set via [33/WAKU2-DISCV5](../33/discv5.md). (As stated in the [Theory and Protocol Semantics Section](#theory-and-protocol-semantics), these peer sets SHOULD be retrieved unsolicitedly before receiving requests to achieve faster response times.) @@ -159,7 +164,7 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public ## References -* [33/WAKU2-DISCV5](https://rfc.vac.dev/spec/33/) +* [33/WAKU2-DISCV5](../33/discv5.md) * [WAKU2-ENR](../enr.md) * [multiaddress](https://docs.libp2p.io/concepts/addressing/) * [libp2p discovery interface](https://github.com/status-im/nim-libp2p/issues/140) From 31402ab1eafab1ff2936a3f786e5846150fd7167 Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Wed, 9 Oct 2024 19:28:51 -0400 Subject: [PATCH 3/8] Update peer-exchange.md --- waku/standards/core/34/peer-exchange.md | 156 ++++++++++++++++-------- 1 file changed, 105 insertions(+), 51 deletions(-) diff --git a/waku/standards/core/34/peer-exchange.md b/waku/standards/core/34/peer-exchange.md index 993e79b8a..4d2f366ad 100644 --- a/waku/standards/core/34/peer-exchange.md +++ b/waku/standards/core/34/peer-exchange.md @@ -16,50 +16,74 @@ This document specifies a simple request-response peer exchange protocol. Responders send information about a requested number of peers. The main purpose of this protocol is providing resource restricted devices with peers. -***Protocol Identifier*** +***Protocol Identifier*** - /vac/waku/peer-exchange/2.0.0-alpha1 +> /vac/waku/peer-exchange/2.0.0-alpha1 ## Background and Motivation -It may not be feasible on resource restricted devices to take part in distributed random sampling ambient peer discovery protocols such as [33/WAKU2-DISCV5](../33/discv5.md). -The Waku peer discovery protocol specified in this document allows resource restricted devices to request a list of peers from a service node. -Network parameters necessary to connect to this service node COULD be learned from a static bootstrapping method or using [EIP-1459: Node Discovery via DNS](https://eips.ethereum.org/EIPS/eip-1459). -The advantage of using Waku peer exchange to discover new peers over using a static peer list or DNS discovery is a more even load distribution. -If a lot of (resource restricted) nodes would use the same service nodes as relay or store nodes, the load on these would be very high. -Heavily used static nodes also add a centralized element. Downtime of such a node might significantly impact the network. - -However, the resource efficiency of this protocol comes at an anonymity cost, which is explained in the [Security/Privacy Considerations](#securityprivacy-considerations) section. +It may not be feasible, on resource restricted devices, +to take part in distributed random sampling ambient peer discovery protocols, +such as [33/WAKU2-DISCV5](../33/discv5.md). +The Waku peer discovery protocol, specified in this document, +allows resource restricted devices to request a list of peers from a service node. +Network parameters necessary to connect to this service node COULD be learned +from a static bootstrapping method or +using [EIP-1459: Node Discovery via DNS](https://eips.ethereum.org/EIPS/eip-1459). +The advantage of using Waku peer exchange to discover new peers, +compared to relying on a static peer list or DNS discovery, is a more even load distribution. +If a lot of (resource restricted) nodes would use the same service nodes as relay +or store nodes, the load on these would be very high. +Heavily used static nodes also add a centralized element. +Downtime of such a node might significantly impact the network. + +However, the resource efficiency of this protocol comes at an anonymity cost, +which is explained in the +[Security/Privacy Considerations](#security-considerations) section. This protocol SHOULD only be used if [33/WAKU2-DISCV5](../33/discv5.md) is infeasible. ## Theory and Protocol Semantics -The peer exchange protocol specified in this document is a simple request-response protocol. -As Figure 1 illustrates, the requesting node sends a request to a peer, which acts as the responder. +The peer exchange protocol, specified in this document, +is a simple request-response protocol. +As Figure 1 illustrates, the requesting node sends a request to a peer, +which acts as the responder. The responder replies with a list of ENRs as specified in [WAKU2-ENR](../enr.md). -The [multiaddresses](https://docs.libp2p.io/concepts/addressing/) used to connect to the respective peers can be extracted from the ENRs. +The [multiaddresses](https://docs.libp2p.io/concepts/addressing/) +used to connect to the respective peers can be extracted from the ENRs. ![Figure 1: The responder provides a list of ENRs to the requester. These ENRs contain the information necessary for connecting to the respective peers.](../../images/protocol.svg) -In order to protect its anonymity, the responder MUST NOT provide peers from its actively used peer list as this opens pathways to *Neighbourhood Surveillance* attacks, as described in the -[Security/Privacy Considerations Section](#securityprivacy-considerations). -The responder SHOULD provide a set of peers that has been retrieved using ambient peer discovery methods supporting random sampling, e.g. [33/WAKU2-DISCV5](../33/discv5.md). +In order to protect its anonymity, +the responder MUST NOT provide peers from its actively used peer list +as this opens pathways to *Neighbourhood Surveillance* attacks, as described in the +[Security/Privacy Considerations Section](#security-considerations). +The responder SHOULD provide a set of peers +that has been retrieved using ambient peer discovery methods supporting random sampling, +e.g. [33/WAKU2-DISCV5](../33/discv5.md). This both protects the responder's anonymity as well as helps distributing load. -To allow for fast responses, responders SHOULD retrieve peers unsolicited (before receiving a query) -and maintain a queue of peers for the purpose of providing them in peer exchange responses. -To get the best anonymity properties with respect to response peer sets, responders SHOULD use each of these peers only once. +To allow for fast responses, responders SHOULD retrieve peers unsolicited +(before receiving a query) and +maintain a queue of peers for the purpose of providing them in peer exchange responses. +To get the best anonymity properties with respect to response peer sets, +responders SHOULD use each of these peers only once. To save bandwidth, and as a trade off to anonymity, -responders MAY maintain a larger cache of exchange peers and randomly sample response sets from this local cache. -The size of the cache SHOULD be large enough to allow randomly sampling peer sets that (on average) do not overlap too much. +responders MAY maintain a larger cache of exchange peers and +randomly sample response sets from this local cache. +The size of the cache SHOULD be large enough to allow randomly sampling peer sets +that (on average) do not overlap too much. The responder SHOULD periodically replace the oldest peers in the cache. -This document provides recommended choices for the cache size in the [Implementation Suggestions Section](#implementation-suggestions). +This document provides recommended choices for the cache size in the +[Implementation Suggestions Section](#implementation-suggestions). -Requesters, in the context of the specified peer exchange protocol, SHOULD be resource restricted devices. -While any node could technically act as a requester, using the peer exchange protocol comes with two drawbacks: +Requesters, in the context of the specified peer exchange protocol, +SHOULD be resource restricted devices. +While any node could technically act as a requester, +using the peer exchange protocol comes with two drawbacks: -* reducing [anonymity](#securityprivacy-considerations) +* reducing [anonymity](#security-considerations) * causing load on responder nodes ## Wire Format Specification @@ -90,70 +114,100 @@ The `enr` field contains a Waku ENR as specified in [WAKU2-ENR](../enr.md). Requesters send a `PeerExchangeQuery` to a peer. Responders SHOULD include a maximum of `num_peers` `PeerInfo` instances into a response. -Responders send a `PeerExchangeResponse` to requesters containing a list of `PeerInfo` instances, which in turn hold an ENR. +Responders send a `PeerExchangeResponse` to requesters +containing a list of `PeerInfo` instances, which in turn hold an ENR. ## Implementation Suggestions ### Discovery Interface -Implementations can implement the libp2p discovery interface (e.g. [nim](https://github.com/status-im/nim-libp2p/issues/140), [javascript](https://github.com/libp2p/js-libp2p-interfaces/tree/master/packages/interface-peer-discovery)). +Implementations can implement the libp2p discovery interface +(e.g. [nim](https://github.com/status-im/nim-libp2p/issues/140), +[javascript](https://github.com/libp2p/js-libp2p-interfaces/tree/master/packages/interface-peer-discovery)). ### Exchange Peer Cache Size -The size of the (optional) exchange peer cache discussed in [Theory and Protocol Semantics](#theory-and-protocol-semantics) -depends on the average number of requested peers, which is expected to be the outbound degree of the underlying -[libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md) mesh network. +The size of the (optional) exchange peer cache discussed in +[Theory and Protocol Semantics](#theory-and-protocol-semantics) +depends on the average number of requested peers, +which is expected to be the outbound degree of the underlying +[libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md) +mesh network. The recommended value for this outbound degree is 6 (see parameter `D` in [29/WAKU2-CONFIG](https://rfc.vac.dev/spec/29/)). It is recommended for the cache to hold at least 10 times as many peers (60). -The recommended cache size also depends on the number of requesters a responder is expected to serve within a *refresh cycle*. -A refresh cycle is the time interval in which all peers in the cache are expected to be replaced. -If the number of requests expected per refresh cycle exceeds 600 (10 times the above recommended 60), +The RECCOMENDED cache size also depends on the number of requesters a responder +is expected to serve within a *refresh cycle*. +A refresh cycle is the time interval in which all peers in the cache +are expected to be replaced. +If the number of requests expected per refresh cycle exceeds 600 +(10 times the above recommended 60), it is recommended to increase the cache size to at least a tenth of that number. We will investigate peer exchange cache sizes and refresh strategies, -and provide suggestions based on that in future versions (draft, stable) of this document. +and provide suggestions based on that in future versions +(draft, stable) of this document. + +## Security Considerations -## Security/Privacy/Anonymity Considerations +### Privacy and Anonymity -The peer exchange protocol specified in this document comes with anonymity and security implications. +The peer exchange protocol specified in this document comes with anonymity and +security implications. We differentiate these implications into the requester and responder side, respectively. ### Requester -With a simple peer exchange protocol, the requester is inherently susceptible to both *neighbourhood surveillance* and *controlled neighbourhood* attacks. +With a simple peer exchange protocol, +the requester is inherently susceptible to both *neighbourhood surveillance* and +*controlled neighbourhood* attacks. -To mount a *neighbourhood surveillance* attack, an attacker has to connect to the peers of the victim node. +To mount a *neighbourhood surveillance* attack, +an attacker has to connect to the peers of the victim node. The peer exchange protocol allows a malicious responder to easily get into this position. -The responder connects to a set of peers and simply returns this set of peers to the requester. +The responder connects to a set of peers and +simply returns this set of peers to the requester. -The peer exchange protocol also makes it much easier to get into the position required for the *controlled neighbourhood* attack: +The peer exchange protocol also makes it much easier to get into the position +required for the *controlled neighbourhood* attack: A malicious responder provides controlled peers in the response peer list. More on these attacks may be found in our [research log article](https://vac.dev/wakuv2-relay-anon). -As a weak mitigation the requester MAY ask several peers and select a subset of the returned peers. +As a weak mitigation the requester MAY ask several peers and +select a subset of the returned peers. ### Responder -Responders that answer with active mesh peers are more vulnerable to a *neighbourhood surveillance* attack. -Responding with the set of active mesh peers allows a malicious requester to get into the required position more easily. -It takes away the first hurdle of the *neighbourhood surveillance* attack: The attacker knows which peers to try to connect to. -This increased vulnerability can be avoided by only responding with randomly sampled sets of peers, e.g. by requesting a random peer set via [33/WAKU2-DISCV5](../33/discv5.md). +Responders that answer with active mesh peers are more vulnerable +to a *neighbourhood surveillance* attack. +Responding with the set of active mesh peers allows a malicious requester to +get into the required position more easily. +It takes away the first hurdle of the *neighbourhood surveillance* attack: +The attacker knows which peers to try to connect to. +This increased vulnerability can be avoided by only responding +with randomly sampled sets of peers, +e.g. by requesting a random peer set via [33/WAKU2-DISCV5](../33/discv5.md). (As stated in the [Theory and Protocol Semantics Section](#theory-and-protocol-semantics), -these peer sets SHOULD be retrieved unsolicitedly before receiving requests to achieve faster response times.) +these peer sets SHOULD be retrieved unsolicitedly before +receiving requests to achieve faster response times.) Responders are also susceptible to amplification DoS attacks. -Requesters send a simple message request which causes responders to engage in ambient peer discovery to retrieve a new random peer set. -As a mitigation, responders MAY feature a `seen cache` for requests and only answer once per time interval. -The exchange-peer cache discussed in [Theory and Protocol Semantics Section](#theory-and-protocol-semantics) also provides mitigation. -Still, frequent queries can tigger the refresh cycle more often. The `seen cache` MAY be used in conjunction to provide additional mitigation. +Requesters send a simple message request which causes responders to +engage in ambient peer discovery to retrieve a new random peer set. +As a mitigation, responders MAY feature a `seen cache` for requests and +only answer once per time interval. +The exchange-peer cache discussed in [Theory and Protocol Semantics Section](#theory-and-protocol-semantics) +also provides mitigation. +Still, frequent queries can tigger the refresh cycle more often. +The `seen cache` MAY be used in conjunction to provide additional mitigation. ### Further Considerations The response field contains ENRs as specified in [WAKU2-ENR](../enr.md). While ENRs contain signatures, they do not violate the [Waku relay no-sign policy](https://rfc.vac.dev/spec/11/#signature-policy)), -because they are part of the discovery domain and are not propagated in the relay domain. +because they are part of the discovery domain and +are not propagated in the relay domain. However, there might still be some form of leakage: ENRs could be used to track peers and facilitate linking attacks. We will investigate this further in our Waku anonymity analysis. From 28d24afba76640b30ad0573fbbffcb2e983123eb Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Thu, 10 Oct 2024 22:12:19 -0400 Subject: [PATCH 4/8] Update peer-exchange.md --- waku/standards/core/34/peer-exchange.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/waku/standards/core/34/peer-exchange.md b/waku/standards/core/34/peer-exchange.md index 4d2f366ad..e04cad88e 100644 --- a/waku/standards/core/34/peer-exchange.md +++ b/waku/standards/core/34/peer-exchange.md @@ -48,7 +48,7 @@ The peer exchange protocol, specified in this document, is a simple request-response protocol. As Figure 1 illustrates, the requesting node sends a request to a peer, which acts as the responder. -The responder replies with a list of ENRs as specified in [WAKU2-ENR](../enr.md). +The responder replies with a list of ENRs as specified in [WAKU2-ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md). The [multiaddresses](https://docs.libp2p.io/concepts/addressing/) used to connect to the respective peers can be extracted from the ENRs. @@ -110,7 +110,7 @@ message PeerExchangeRPC { ``` -The `enr` field contains a Waku ENR as specified in [WAKU2-ENR](../enr.md). +The `enr` field contains a Waku ENR as specified in [WAKU2-ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md). Requesters send a `PeerExchangeQuery` to a peer. Responders SHOULD include a maximum of `num_peers` `PeerInfo` instances into a response. @@ -133,7 +133,7 @@ depends on the average number of requested peers, which is expected to be the outbound degree of the underlying [libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md) mesh network. -The recommended value for this outbound degree is 6 (see parameter `D` in [29/WAKU2-CONFIG](https://rfc.vac.dev/spec/29/)). +The recommended value for this outbound degree is 6 (see parameter `D` in [29/WAKU2-CONFIG](../../../informational/29/config.md)). It is recommended for the cache to hold at least 10 times as many peers (60). The RECCOMENDED cache size also depends on the number of requesters a responder @@ -204,8 +204,8 @@ The `seen cache` MAY be used in conjunction to provide additional mitigation. ### Further Considerations -The response field contains ENRs as specified in [WAKU2-ENR](../enr.md). -While ENRs contain signatures, they do not violate the [Waku relay no-sign policy](https://rfc.vac.dev/spec/11/#signature-policy)), +The response field contains ENRs as specified in [WAKU2-ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md). +While ENRs contain signatures, they do not violate the [Waku relay no-sign policy](../11/waku2.md/#signature-policy)), because they are part of the discovery domain and are not propagated in the relay domain. However, there might still be some form of leakage: @@ -219,9 +219,9 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public ## References * [33/WAKU2-DISCV5](../33/discv5.md) -* [WAKU2-ENR](../enr.md) +* [WAKU2-ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md) * [multiaddress](https://docs.libp2p.io/concepts/addressing/) * [libp2p discovery interface](https://github.com/status-im/nim-libp2p/issues/140) * [libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md) -* [29/WAKU2-CONFIG](https://rfc.vac.dev/spec/29/) +* [29/WAKU2-CONFIG](../../../informational/29/config.md) * [Waku relay anonymity](https://vac.dev/wakuv2-relay-anon) From 2921190e080eb03f2d7cd56c065722b0790e4617 Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Wed, 23 Oct 2024 23:02:18 -0400 Subject: [PATCH 5/8] To-peer --- waku/standards/core/34/protocol.svg | 118 ++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 waku/standards/core/34/protocol.svg diff --git a/waku/standards/core/34/protocol.svg b/waku/standards/core/34/protocol.svg new file mode 100644 index 000000000..dda2157af --- /dev/null +++ b/waku/standards/core/34/protocol.svg @@ -0,0 +1,118 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From 1a84e4b236f0c329d6bd9c6749c93014f467a4c1 Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Wed, 23 Oct 2024 23:02:58 -0400 Subject: [PATCH 6/8] Rename waku/standards/core/34/protocol.svg to waku/standards/core/34/images/protocol.svg --- waku/standards/core/34/{ => images}/protocol.svg | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename waku/standards/core/34/{ => images}/protocol.svg (100%) diff --git a/waku/standards/core/34/protocol.svg b/waku/standards/core/34/images/protocol.svg similarity index 100% rename from waku/standards/core/34/protocol.svg rename to waku/standards/core/34/images/protocol.svg From cd7a6d335a4827630f67164908b2669a469829b7 Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Wed, 23 Oct 2024 23:17:14 -0400 Subject: [PATCH 7/8] Update peer-exchange.md --- waku/standards/core/34/peer-exchange.md | 48 +++++++++++++------------ 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/waku/standards/core/34/peer-exchange.md b/waku/standards/core/34/peer-exchange.md index e04cad88e..5b0262a4e 100644 --- a/waku/standards/core/34/peer-exchange.md +++ b/waku/standards/core/34/peer-exchange.md @@ -1,7 +1,7 @@ --- slug: 34 title: 34/WAKU2-PEER-EXCHANGE -name: Waku v2 Peer Exchange +name: Waku2 Peer Exchange status: draft category: Standards Track tags: waku/core-protocol @@ -24,7 +24,7 @@ The main purpose of this protocol is providing resource restricted devices with It may not be feasible, on resource restricted devices, to take part in distributed random sampling ambient peer discovery protocols, -such as [33/WAKU2-DISCV5](../33/discv5.md). +such as [33/WAKU2-DISCV5](/waku/standards/core/33/discv5.md). The Waku peer discovery protocol, specified in this document, allows resource restricted devices to request a list of peers from a service node. Network parameters necessary to connect to this service node COULD be learned @@ -32,7 +32,7 @@ from a static bootstrapping method or using [EIP-1459: Node Discovery via DNS](https://eips.ethereum.org/EIPS/eip-1459). The advantage of using Waku peer exchange to discover new peers, compared to relying on a static peer list or DNS discovery, is a more even load distribution. -If a lot of (resource restricted) nodes would use the same service nodes as relay +If a lot of resource restricted nodes would use the same service nodes as relay or store nodes, the load on these would be very high. Heavily used static nodes also add a centralized element. Downtime of such a node might significantly impact the network. @@ -40,9 +40,12 @@ Downtime of such a node might significantly impact the network. However, the resource efficiency of this protocol comes at an anonymity cost, which is explained in the [Security/Privacy Considerations](#security-considerations) section. -This protocol SHOULD only be used if [33/WAKU2-DISCV5](../33/discv5.md) is infeasible. +This protocol SHOULD only be used if [33/WAKU2-DISCV5](/waku/standards/core/33/discv5.md) is infeasible. ## Theory and Protocol Semantics +The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, +“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and +“OPTIONAL” in this document are to be interpreted as described in [2119](https://www.ietf.org/rfc/rfc2119.txt). The peer exchange protocol, specified in this document, is a simple request-response protocol. @@ -52,7 +55,7 @@ The responder replies with a list of ENRs as specified in [WAKU2-ENR](https://gi The [multiaddresses](https://docs.libp2p.io/concepts/addressing/) used to connect to the respective peers can be extracted from the ENRs. -![Figure 1: The responder provides a list of ENRs to the requester. These ENRs contain the information necessary for connecting to the respective peers.](../../images/protocol.svg) +![Figure 1: The responder provides a list of ENRs to the requester. These ENRs contain the information necessary for connecting to the respective peers.](/waku/standards/core/34/images/protocol.svg) In order to protect its anonymity, the responder MUST NOT provide peers from its actively used peer list @@ -60,7 +63,7 @@ as this opens pathways to *Neighbourhood Surveillance* attacks, as described in [Security/Privacy Considerations Section](#security-considerations). The responder SHOULD provide a set of peers that has been retrieved using ambient peer discovery methods supporting random sampling, -e.g. [33/WAKU2-DISCV5](../33/discv5.md). +e.g. [33/WAKU2-DISCV5](/waku/standards/core/33/discv5.md). This both protects the responder's anonymity as well as helps distributing load. To allow for fast responses, responders SHOULD retrieve peers unsolicited @@ -75,7 +78,7 @@ randomly sample response sets from this local cache. The size of the cache SHOULD be large enough to allow randomly sampling peer sets that (on average) do not overlap too much. The responder SHOULD periodically replace the oldest peers in the cache. -This document provides recommended choices for the cache size in the +The RECOMMENDED options for the cache size are described in the [Implementation Suggestions Section](#implementation-suggestions). Requesters, in the context of the specified peer exchange protocol, @@ -121,9 +124,9 @@ containing a list of `PeerInfo` instances, which in turn hold an ENR. ### Discovery Interface -Implementations can implement the libp2p discovery interface -(e.g. [nim](https://github.com/status-im/nim-libp2p/issues/140), -[javascript](https://github.com/libp2p/js-libp2p-interfaces/tree/master/packages/interface-peer-discovery)). +Implementations can implement the libp2p discovery interface: +- [nim](https://github.com/status-im/nim-libp2p/issues/140) +- [javascript](https://github.com/libp2p/js-libp2p-interfaces/tree/master/packages/interface-peer-discovery). ### Exchange Peer Cache Size @@ -133,8 +136,8 @@ depends on the average number of requested peers, which is expected to be the outbound degree of the underlying [libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md) mesh network. -The recommended value for this outbound degree is 6 (see parameter `D` in [29/WAKU2-CONFIG](../../../informational/29/config.md)). -It is recommended for the cache to hold at least 10 times as many peers (60). +The RECOMMENDED value for this outbound degree is 6 (see parameter `D` in [29/WAKU2-CONFIG](/waku/informational/29/config.md)). +It is RECOMMENDED for the cache to hold at least 10 times as many peers (60). The RECCOMENDED cache size also depends on the number of requesters a responder is expected to serve within a *refresh cycle*. @@ -142,11 +145,7 @@ A refresh cycle is the time interval in which all peers in the cache are expected to be replaced. If the number of requests expected per refresh cycle exceeds 600 (10 times the above recommended 60), -it is recommended to increase the cache size to at least a tenth of that number. - -We will investigate peer exchange cache sizes and refresh strategies, -and provide suggestions based on that in future versions -(draft, stable) of this document. +it is RECOMMENDED to increase the cache size to at least a tenth of that number. ## Security Considerations @@ -187,7 +186,7 @@ It takes away the first hurdle of the *neighbourhood surveillance* attack: The attacker knows which peers to try to connect to. This increased vulnerability can be avoided by only responding with randomly sampled sets of peers, -e.g. by requesting a random peer set via [33/WAKU2-DISCV5](../33/discv5.md). +e.g. by requesting a random peer set via [33/WAKU2-DISCV5](/waku/standards/core/33/discv5.md). (As stated in the [Theory and Protocol Semantics Section](#theory-and-protocol-semantics), these peer sets SHOULD be retrieved unsolicitedly before receiving requests to achieve faster response times.) @@ -205,7 +204,7 @@ The `seen cache` MAY be used in conjunction to provide additional mitigation. ### Further Considerations The response field contains ENRs as specified in [WAKU2-ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md). -While ENRs contain signatures, they do not violate the [Waku relay no-sign policy](../11/waku2.md/#signature-policy)), +While ENRs contain signatures, they do not violate the [Waku relay no-sign policy](/waku/standards/core/11/relay.md#signature-policy), because they are part of the discovery domain and are not propagated in the relay domain. However, there might still be some form of leakage: @@ -218,10 +217,13 @@ Copyright and related rights waived via [CC0](https://creativecommons.org/public ## References -* [33/WAKU2-DISCV5](../33/discv5.md) +* [33/WAKU2-DISCV5](/waku/standards/core/33/discv5.md) +* [EIP-1459: Node Discovery via DNS](https://eips.ethereum.org/EIPS/eip-1459) * [WAKU2-ENR](https://github.com/waku-org/specs/blob/master/standards/core/enr.md) * [multiaddress](https://docs.libp2p.io/concepts/addressing/) -* [libp2p discovery interface](https://github.com/status-im/nim-libp2p/issues/140) +* [libp2p discovery interface in nim](https://github.com/status-im/nim-libp2p/issues/140) +* [libp2p discovery interface in javascript](https://github.com/libp2p/js-libp2p-interfaces/tree/master/packages/interface-peer-discovery) * [libp2p gossipsub](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md) -* [29/WAKU2-CONFIG](../../../informational/29/config.md) -* [Waku relay anonymity](https://vac.dev/wakuv2-relay-anon) +* [29/WAKU2-CONFIG](/waku/informational/29/config.md) +* [Waku Relay Anonymity](https://vac.dev/wakuv2-relay-anon) +* [Waku relay no-sign policy](/waku/standards/core/11/relay.md#signature-policy) From 0f889e5fc92549010c70f800a2c7e6469a1a8791 Mon Sep 17 00:00:00 2001 From: Jimmy Debe <91767824+jimstir@users.noreply.github.com> Date: Tue, 5 Nov 2024 19:01:27 -0500 Subject: [PATCH 8/8] Update discv5.md --- waku/standards/core/33/discv5.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/waku/standards/core/33/discv5.md b/waku/standards/core/33/discv5.md index 4e16d426f..dd8ada369 100644 --- a/waku/standards/core/33/discv5.md +++ b/waku/standards/core/33/discv5.md @@ -29,8 +29,8 @@ For establishing and growing this network, new nodes trying to join the Waku2 ne [10/WAKU2](../10/waku2.md) supports the following discovery methods in order of increasing decentralization * hard coded bootstrap nodes -* [`DNS discovery`](https://rfc.vac.dev/spec/10/#discovery-domain) (based on [EIP-1459](https://eips.ethereum.org/EIPS/eip-1459)) -* `peer-exchange` (work in progress) +* [`DNS discovery`](/waku/standards/10/waku2.md/#discovery-domain) (based on [EIP-1459](https://eips.ethereum.org/EIPS/eip-1459)) +* [`34/WAKU2-PEER-EXCHANGE`](/waku/standards/core/34/peer-exchange.md) * `33/WAKU2-DISCV5` (specified in this document) The purpose of ambient node discovery within [10/WAKU2](../10/waku2.md) is discovering Waku2 nodes in a decentralized way. @@ -156,13 +156,13 @@ Properly protecting against eclipse attacks is challenging and raises research q ## References 1. [10/WAKU2](../10/waku2.md) +2. [`34/WAKU2-PEER-EXCHANGE`](/waku/standards/core/34/peer-exchange.md) 1. [11/WAKU2-RELAY](../11/relay.md) 1. [`31/WAKU2-ENR`](https://github.com/waku-org/specs/blob/waku-RFC/standards/core/enr.md) 1. [Node Discovery Protocol v5 (`discv5`)](https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md) 1. [`discv5` semantics](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-theory.md). 1. [`discv5` wire protocol](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-wire.md) 1. [`discv5` topic discovery](https://github.com/ethereum/devp2p/blob/master/discv5/discv5-theory.md#topic-advertisement) -1. [Waku DNS discovery](https://rfc.vac.dev/spec/10/#discovery-domain) 1. [libp2p AutoNAT protocol](https://github.com/libp2p/specs/blob/master/autonat/README.md) 1. [`EIP-1459`](https://eips.ethereum.org/EIPS/eip-1459) 1. [`GossipSub`](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/README.md)