From 9dca1ca0b7f467b040bfdc881dd6381625324af0 Mon Sep 17 00:00:00 2001 From: Hanno Cornelius Date: Fri, 9 Dec 2022 13:05:54 +0200 Subject: [PATCH 01/12] docs: improved filter specification --- content/docs/rfcs/12/README.md | 201 ++++++++++++++++++++++----------- 1 file changed, 137 insertions(+), 64 deletions(-) diff --git a/content/docs/rfcs/12/README.md b/content/docs/rfcs/12/README.md index 8ca07bd38..a1eb17e48 100644 --- a/content/docs/rfcs/12/README.md +++ b/content/docs/rfcs/12/README.md @@ -16,7 +16,9 @@ contributors: # Content filtering -**Protocol identifier***: `/vac/waku/filter/2.0.0-beta1` +**Protocol identifiers***: +_filter-subscribe_: `/vac/waku/filter-subscribe/2.0.0-beta1` +_filter-push_: `/vac/waku/filter-push/2.0.0-beta1` Content filtering is a way to do [message-based filtering](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_filtering). @@ -61,77 +63,148 @@ The following are not considered as part of the adversarial model: ## Protobuf ```protobuf -message FilterRequest { - bool subscribe = 1; - string topic = 2; - repeated ContentFilter contentFilters = 3; - - message ContentFilter { - string contentTopic = 1; +syntax = "proto3"; + +// 12/WAKU2-FILTER rfc: https://rfc.vac.dev/spec/12/ +package waku.filter.v2; + +// Protocol identifier: /vac/waku/filter-subscribe/2.0.0-beta1 +message FilterSubscribeRequest { + enum FilterSubscribeType { + SUBSCRIBER_PING = 0; + SUBSCRIBE = 1; + UNSUBSCRIBE = 2; + UNSUBSCRIBE_ALL = 3; } + + string request_id = 1; + FilterSubscribeType filter_subscribe_type = 2; + + // Filter criteria + optional string pubsub_topic = 10; + repeated string content_topics = 11; } -message MessagePush { - repeated WakuMessage messages = 1; +message FilterSubscribeResponse { + string request_id = 1; + uint32 status_code = 10; + optional string status_desc = 11; } -message FilterRPC { - string requestId = 1; - FilterRequest request = 2; - MessagePush push = 3; +// Protocol identifier: /vac/waku/filter-push/2.0.0-beta1 +message MessagePush { + WakuMessage waku_message = 1; } ``` -#### FilterRPC - -A node MUST send all Filter messages (`FilterRequest`, `MessagePush`) wrapped inside a -`FilterRPC` this allows the node handler to determine how to handle a message as the Waku -Filter protocol is not a request response based protocol but instead a push based system. - -The `requestId` MUST be a uniquely generated string. When a `MessagePush` is sent -the `requestId` MUST match the `requestId` of the subscribing `FilterRequest` whose filters -matched the message causing it to be pushed. - -#### FilterRequest - -A `FilterRequest` contains an optional topic, zero or more content filters and -a boolean signifying whether to subscribe or unsubscribe to the given filters. -True signifies 'subscribe' and false signifies 'unsubscribe'. - -A node that sends the RPC with a filter request and `subscribe` set to 'true' -requests that the filter node SHOULD notify the light requesting node of messages -matching this filter. - -A node that sends the RPC with a filter request and `subscribe` set to 'false' -requests that the filter node SHOULD stop notifying the light requesting node -of messages matching this filter if it is currently doing so. - -The filter matches when content filter and, optionally, a topic is matched. -Content filter is matched when a `WakuMessage` `contentTopic` field is the same. - -A filter node SHOULD honor this request, though it MAY choose not to do so. If -it chooses not to do so it MAY tell the light why. The mechanism for doing this -is currently not specified. For notifying the light node a filter node sends a -MessagePush message. - -Since such a filter node is doing extra work for a light node, it MAY also -account for usage and be selective in how much service it provides. This -mechanism is currently planned but underspecified. - -#### MessagePush - -A filter node that has received a filter request SHOULD push all messages that -match this filter to a light node. These [`WakuMessage`'s](./waku-message.md) are likely to come from the -`relay` protocol and be kept at the Node, but there MAY be other sources or -protocols where this comes from. This is up to the consumer of the protocol. - -A filter node MUST NOT send a push message for messages that have not been -requested via a FilterRequest. - -If a specific light node isn't connected to a filter node for some specific -period of time (e.g. a TTL), then the filter node MAY choose to not push these -messages to the node. This period is up to the consumer of the protocol and node -implementation, though a reasonable default is one minute. +## Filter-Subscribe + +A filter service node MUST support the _filter-subscribe_ protocol +to allow filter clients to subscribe, modify, refresh and unsubscribe a desired set of filter criteria. +The combination of different filter criteria for a specific filter client node is termed a "subscription". +A filter client is interested in receiving messages matching the filter criteria in its registered subscriptions. +It is RECOMMENDED that filter service nodes allow only one subscription per client. + +Since a filter service node is consuming resources to provide this service, +it MAY account for usage and adapt its service provision to certain clients. +An incentive mechanism is currently planned but underspecified. + +### Filter Subscribe Request + +A client node MUST send all filter requests in a `FilterSubscribeRequest` message. +This request MUST contain a `request_id`. +The `request_id` MUST be a uniquely generated string. +Each request MUST include a `filter_subscribe_type`, indicating the type of request. + +### Filter Subscribe Response + +In return to any `FilterSubscribeRequest`, +a filter service node SHOULD respond with a `FilterSubscribeResponse` with a `requestId` matching that of the request. +This response MUST contain a `status_code` indicating if the request was successful or not. +Successful status codes are in the `2xx` range. +Client nodes SHOULD consider all other status codes as error codes and assume that the requested operation had failed. +In addition, the filter service node MAY choose to provide a more detailed status description in the `status_desc` field. + +### Filter matching + +In the description of each request type below, +the term "filter criteria" refers to the combination of `pubsub_topic` and a set of `content_topics`. +The request MAY include filter criteria, conditional to the selected `filter_subscribe_type`. +The `pubsub_topic` is always optional in filter criteria. +A `WakuMessage` matches filter criteria when its `content_topic` is in the `content_topics` set +and, if included in the criteria, it was published on a matching `pubsub_topic`. +If the `pubsub_topic` is set and not empty, +a `WakuMessage` will only match the filter criteria if it has a matching `content_topic` and was published on _the same_ `pubsub_topic`. +If the `pubsub_topic` is either empty or unset, +a `WakuMessage` will match the filter criteria if it has a matching `content_topic` and was published on _any_ `pubsub_topic`. + +### Filter Subscribe Types + +The following filter subscribe types are defined: + +#### SUBSCRIBER_PING + +A filter client that sends a `FilterSubscribeRequest` with `filter_subscribe_type` set to `SUBSCRIBER_PING` +requests that the service node SHOULD indicate if it has any active subscriptions for this client. +The filter client SHOULD exclude any filter criteria from the request. +The filter service node SHOULD respond with a success code if it has any active subscriptions for this client +or an error code if not. + +#### SUBSCRIBE + +A filter client that sends a `FilterSubscribeRequest` with `filter_subscribe_type` set to `SUBSCRIBE` +requests that the service node SHOULD push messages matching this filter to the client. +The filter client MUST include the desired filter criteria in the request. +A client MAY use this request type to _modify_ an existing subscription +by providing _additional_ filter criteria in a new request. +A client MAY use this request type to _refresh_ an existing subscription +by providing _the same_ filter criteria in a new request. +The filter service node SHOULD respond with a success code if it successfully honored this request +or an error code if not. + +#### UNSUBSCRIBE + +A filter client that sends a `FilterSubscribeRequest` with `filter_subscribe_type` set to `UNSUBSCRIBE` +requests that the service node SHOULD _stop_ pushing messages matching this filter to the client. +The filter client MUST include the filter criteria it desires to unsubscribe from in the request. +A client MAY use this request type to _modify_ an existing subscription +by providing _a subset of_ the original filter criteria to unsubscribe from in a new request. +The filter service node SHOULD respond with a success code if it successfully honored this request +or an error code if not. + +#### UNSUBSCRIBE_ALL + +A filter client that sends a `FilterSubscribeRequest` with `filter_subscribe_type` set to `UNSUBSCRIBE_ALL` +requests that the service node SHOULD _stop_ pushing messages matching _any_ filter to the client. +The filter client SHOULD exclude any filter criteria from the request. +The filter service node SHOULD remove any existing subscriptions for this client. +It SHOULD respond with a success code if it successfully honored this request +or an error code if not. + +## Filter-Push + +A filter client node MUST support the _filter-push_ protocol +to allow filter service nodes to push messages matching registered subscriptions to this client. + +A filter service node SHOULD push all messages +matching the filter criteria in a registered subscription +to the subscribed filter client. +These [`WakuMessage`s](./waku-message.md) are likely to come from [`11/WAKU2-RELAY`](https://rfc.vac.dev/spec/11/), +but there MAY be other sources or protocols where this comes from. +This is up to the consumer of the protocol. + +If a specific filter client node is not reachable from the service node for a period of time, +the filter service node MAY choose to stop pushing messages to the client and remove its subscription. +This period is up to the service node implementation. +We consider `1 minute` to be a reasonable default. + +### Message Push + +Each message MUST be pushed in a `MessagePush` message. +Each `MessagePush` MUST contain one (and only one) `waku_message`. +A filter client SHOULD NOT respond to a `MessagePush`. +Since the filter protocol does not include caching or fault-tolerance, +this is a best effort push service with no bundling or retransmission of messages. --- # Future Work From d2d80b67ce26aef2b66877c3d5ad4813b7f755ba Mon Sep 17 00:00:00 2001 From: Hanno Cornelius Date: Fri, 9 Dec 2022 15:49:10 +0200 Subject: [PATCH 02/12] docs: added pubsub topic to push --- content/docs/rfcs/12/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/content/docs/rfcs/12/README.md b/content/docs/rfcs/12/README.md index a1eb17e48..d24dbf96c 100644 --- a/content/docs/rfcs/12/README.md +++ b/content/docs/rfcs/12/README.md @@ -94,6 +94,7 @@ message FilterSubscribeResponse { // Protocol identifier: /vac/waku/filter-push/2.0.0-beta1 message MessagePush { WakuMessage waku_message = 1; + optional string pubsub_topic = 2; } ``` @@ -202,6 +203,8 @@ We consider `1 minute` to be a reasonable default. Each message MUST be pushed in a `MessagePush` message. Each `MessagePush` MUST contain one (and only one) `waku_message`. +If this message was received on a specific `pubsub_topic`, +it SHOULD be included in the `MessagePush`. A filter client SHOULD NOT respond to a `MessagePush`. Since the filter protocol does not include caching or fault-tolerance, this is a best effort push service with no bundling or retransmission of messages. From 4f43a25a3770de5f7f5a276fb987930ccefa20f0 Mon Sep 17 00:00:00 2001 From: Hanno Cornelius Date: Mon, 12 Dec 2022 10:45:47 +0200 Subject: [PATCH 03/12] fix: formatting fix --- content/docs/rfcs/12/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/rfcs/12/README.md b/content/docs/rfcs/12/README.md index d24dbf96c..0d90dd189 100644 --- a/content/docs/rfcs/12/README.md +++ b/content/docs/rfcs/12/README.md @@ -16,9 +16,9 @@ contributors: # Content filtering -**Protocol identifiers***: -_filter-subscribe_: `/vac/waku/filter-subscribe/2.0.0-beta1` -_filter-push_: `/vac/waku/filter-push/2.0.0-beta1` +**Protocol identifiers**: +- _filter-subscribe_: `/vac/waku/filter-subscribe/2.0.0-beta1` +- _filter-push_: `/vac/waku/filter-push/2.0.0-beta1` Content filtering is a way to do [message-based filtering](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_filtering). From 29ae394238577209814e8a166eb25ec16bbe0c08 Mon Sep 17 00:00:00 2001 From: Hanno Cornelius Date: Tue, 13 Dec 2022 16:02:30 +0200 Subject: [PATCH 04/12] docs: remove confusing recommendation --- content/docs/rfcs/12/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/docs/rfcs/12/README.md b/content/docs/rfcs/12/README.md index 0d90dd189..0b0d7f415 100644 --- a/content/docs/rfcs/12/README.md +++ b/content/docs/rfcs/12/README.md @@ -104,7 +104,6 @@ A filter service node MUST support the _filter-subscribe_ protocol to allow filter clients to subscribe, modify, refresh and unsubscribe a desired set of filter criteria. The combination of different filter criteria for a specific filter client node is termed a "subscription". A filter client is interested in receiving messages matching the filter criteria in its registered subscriptions. -It is RECOMMENDED that filter service nodes allow only one subscription per client. Since a filter service node is consuming resources to provide this service, it MAY account for usage and adapt its service provision to certain clients. From cd3e880889c8305dfe35f09a40a2cec8989f2b43 Mon Sep 17 00:00:00 2001 From: Hanno Cornelius Date: Thu, 26 Jan 2023 16:43:38 +0200 Subject: [PATCH 05/12] docs: specify empty filter criteria --- content/docs/rfcs/12/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/docs/rfcs/12/README.md b/content/docs/rfcs/12/README.md index 0b0d7f415..b62851b87 100644 --- a/content/docs/rfcs/12/README.md +++ b/content/docs/rfcs/12/README.md @@ -149,6 +149,7 @@ requests that the service node SHOULD indicate if it has any active subscription The filter client SHOULD exclude any filter criteria from the request. The filter service node SHOULD respond with a success code if it has any active subscriptions for this client or an error code if not. +The filter service node SHOULD ignore any filter criteria in the request. #### SUBSCRIBE From 7c47eb0c60c1b924ec169a53c4b6f0188adf9015 Mon Sep 17 00:00:00 2001 From: Hanno Cornelius Date: Thu, 26 Jan 2023 17:38:34 +0200 Subject: [PATCH 06/12] docs: specify push failure --- content/docs/rfcs/12/README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/content/docs/rfcs/12/README.md b/content/docs/rfcs/12/README.md index b62851b87..2a736033f 100644 --- a/content/docs/rfcs/12/README.md +++ b/content/docs/rfcs/12/README.md @@ -194,6 +194,8 @@ These [`WakuMessage`s](./waku-message.md) are likely to come from [`11/WAKU2-REL but there MAY be other sources or protocols where this comes from. This is up to the consumer of the protocol. +If a message push fails, +the filter service node MAY consider the client node to be unreachable. If a specific filter client node is not reachable from the service node for a period of time, the filter service node MAY choose to stop pushing messages to the client and remove its subscription. This period is up to the service node implementation. @@ -207,7 +209,8 @@ If this message was received on a specific `pubsub_topic`, it SHOULD be included in the `MessagePush`. A filter client SHOULD NOT respond to a `MessagePush`. Since the filter protocol does not include caching or fault-tolerance, -this is a best effort push service with no bundling or retransmission of messages. +this is a best effort push service with no bundling +or guaranteed retransmission of messages. --- # Future Work From 12793c55ae2e25f78fff9a685c7a123a82ffffe9 Mon Sep 17 00:00:00 2001 From: Hanno Cornelius Date: Mon, 20 Mar 2023 12:01:53 +0200 Subject: [PATCH 07/12] docs: clarify mandatory fields for valid filter criteria --- content/docs/rfcs/12/README.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/content/docs/rfcs/12/README.md b/content/docs/rfcs/12/README.md index 2a736033f..2b15d3a33 100644 --- a/content/docs/rfcs/12/README.md +++ b/content/docs/rfcs/12/README.md @@ -130,13 +130,11 @@ In addition, the filter service node MAY choose to provide a more detailed statu In the description of each request type below, the term "filter criteria" refers to the combination of `pubsub_topic` and a set of `content_topics`. The request MAY include filter criteria, conditional to the selected `filter_subscribe_type`. -The `pubsub_topic` is always optional in filter criteria. +If the request contains filter criteria, +it MUST contain a `pubsub_topic` +and the `content_topics` set MUST NOT be empty. A `WakuMessage` matches filter criteria when its `content_topic` is in the `content_topics` set -and, if included in the criteria, it was published on a matching `pubsub_topic`. -If the `pubsub_topic` is set and not empty, -a `WakuMessage` will only match the filter criteria if it has a matching `content_topic` and was published on _the same_ `pubsub_topic`. -If the `pubsub_topic` is either empty or unset, -a `WakuMessage` will match the filter criteria if it has a matching `content_topic` and was published on _any_ `pubsub_topic`. +and it was published on a matching `pubsub_topic`. ### Filter Subscribe Types @@ -162,6 +160,9 @@ A client MAY use this request type to _refresh_ an existing subscription by providing _the same_ filter criteria in a new request. The filter service node SHOULD respond with a success code if it successfully honored this request or an error code if not. +The filter service node SHOULD respond with an error code and discard the request +if the subscribe request does not contain valid filter criteria, +i.e. both a `pubsub_topic` _and_ a non-empty `content_topics` set. #### UNSUBSCRIBE @@ -172,6 +173,9 @@ A client MAY use this request type to _modify_ an existing subscription by providing _a subset of_ the original filter criteria to unsubscribe from in a new request. The filter service node SHOULD respond with a success code if it successfully honored this request or an error code if not. +The filter service node SHOULD respond with an error code and discard the request +if the unsubscribe request does not contain valid filter criteria, +i.e. both a `pubsub_topic` _and_ a non-empty `content_topics` set. #### UNSUBSCRIBE_ALL From 0f02d70dfec8f198e18a77b7d15997f2bb24375f Mon Sep 17 00:00:00 2001 From: Hanno Cornelius Date: Thu, 20 Apr 2023 14:45:08 +0200 Subject: [PATCH 08/12] docs: clarify filter client role in verifying MessagePush --- content/docs/rfcs/12/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/content/docs/rfcs/12/README.md b/content/docs/rfcs/12/README.md index 2b15d3a33..2aa04dcbd 100644 --- a/content/docs/rfcs/12/README.md +++ b/content/docs/rfcs/12/README.md @@ -215,6 +215,9 @@ A filter client SHOULD NOT respond to a `MessagePush`. Since the filter protocol does not include caching or fault-tolerance, this is a best effort push service with no bundling or guaranteed retransmission of messages. +A filter client SHOULD verify that each `MessagePush` it receives +originated from a service node where the client has an active subscription +and that it matches filter criteria belonging to that subscription. --- # Future Work From 7f5cc79d5d95e088628ac63e978200b2301e106b Mon Sep 17 00:00:00 2001 From: Hanno Cornelius Date: Wed, 26 Apr 2023 17:21:19 +0200 Subject: [PATCH 09/12] docs: add link to previous filter draft version --- content/docs/rfcs/12/README.md | 1 + .../rfcs/12/previous-versions/00/README.md | 169 ++++++++++++++++++ 2 files changed, 170 insertions(+) create mode 100644 content/docs/rfcs/12/previous-versions/00/README.md diff --git a/content/docs/rfcs/12/README.md b/content/docs/rfcs/12/README.md index 2aa04dcbd..dd7f679c1 100644 --- a/content/docs/rfcs/12/README.md +++ b/content/docs/rfcs/12/README.md @@ -4,6 +4,7 @@ title: 12/WAKU2-FILTER name: Waku v2 Filter status: draft tags: waku-core +versions: [00](/spec/12/previous-versions/00/), 01 editor: Hanno Cornelius contributors: - Dean Eigenmann diff --git a/content/docs/rfcs/12/previous-versions/00/README.md b/content/docs/rfcs/12/previous-versions/00/README.md new file mode 100644 index 000000000..8ca07bd38 --- /dev/null +++ b/content/docs/rfcs/12/previous-versions/00/README.md @@ -0,0 +1,169 @@ +--- +slug: 12 +title: 12/WAKU2-FILTER +name: Waku v2 Filter +status: draft +tags: waku-core +editor: Hanno Cornelius +contributors: + - Dean Eigenmann + - Oskar Thorén + - Sanaz Taheri + - Ebube Ud +--- + +`WakuFilter` is a protocol that enables subscribing to messages that a peer receives. This is a more lightweight version of `WakuRelay` specifically designed for bandwidth restricted devices. This is due to the fact that light nodes subscribe to full-nodes and only receive the messages they desire. + +# Content filtering + +**Protocol identifier***: `/vac/waku/filter/2.0.0-beta1` + +Content filtering is a way to do [message-based +filtering](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_filtering). +Currently the only content filter being applied is on `contentTopic`. This +corresponds to topics in Waku v1. + +## Rationale + +Unlike the `store` protocol for historical messages, this protocol allows for +native lower latency scenarios such as instant messaging. It is thus +complementary to it. + +Strictly speaking, it is not just doing basic request response, but performs +sender push based on receiver intent. While this can be seen as a form of light +pub/sub, it is only used between two nodes in a direct fashion. Unlike the +Gossip domain, this is meant for light nodes which put a premium on bandwidth. +No gossiping takes place. + +It is worth noting that a light node could get by with only using the `store` +protocol to query for a recent time window, provided it is acceptable to do +frequent polling. + + +# Design Requirements + +The effectiveness and reliability of the content filtering service enabled by `WakuFilter` protocol rely on the *high availability* of the full nodes as the service providers. To this end, full nodes must feature *high uptime* (to persistently listen and capture the network messages) as well as *high Bandwidth* (to provide timely message delivery to the light nodes). + +# Security Consideration + +Note that while using `WakuFilter` allows light nodes to save bandwidth, it comes with a privacy cost in the sense that they need to disclose their liking topics to the full nodes to retrieve the relevant messages. Currently, anonymous subscription is not supported by the `WakuFilter`, however, potential solutions in this regard are sketched below in [Future Work](#future-work) section. + +## Terminology +The term Personally identifiable information (PII) refers to any piece of data that can be used to uniquely identify a user. For example, the signature verification key, and the hash of one's static IP address are unique for each user and hence count as PII. + +# Adversarial Model +Any node running the `WakuFilter` protocol i.e., both the subscriber node and the queried node are considered as an adversary. Furthermore, we consider the adversary as a passive entity that attempts to collect information from other nodes to conduct an attack but it does so without violating protocol definitions and instructions. For example, under the passive adversarial model, no malicious node intentionally hides the messages matching to one's subscribed content filter as it is against the description of the `WakuFilter` protocol. + +The following are not considered as part of the adversarial model: + - An adversary with a global view of all the nodes and their connections. + - An adversary that can eavesdrop on communication links between arbitrary pairs of nodes (unless the adversary is one end of the communication). In specific, the communication channels are assumed to be secure. + +## Protobuf + +```protobuf +message FilterRequest { + bool subscribe = 1; + string topic = 2; + repeated ContentFilter contentFilters = 3; + + message ContentFilter { + string contentTopic = 1; + } +} + +message MessagePush { + repeated WakuMessage messages = 1; +} + +message FilterRPC { + string requestId = 1; + FilterRequest request = 2; + MessagePush push = 3; +} +``` + +#### FilterRPC + +A node MUST send all Filter messages (`FilterRequest`, `MessagePush`) wrapped inside a +`FilterRPC` this allows the node handler to determine how to handle a message as the Waku +Filter protocol is not a request response based protocol but instead a push based system. + +The `requestId` MUST be a uniquely generated string. When a `MessagePush` is sent +the `requestId` MUST match the `requestId` of the subscribing `FilterRequest` whose filters +matched the message causing it to be pushed. + +#### FilterRequest + +A `FilterRequest` contains an optional topic, zero or more content filters and +a boolean signifying whether to subscribe or unsubscribe to the given filters. +True signifies 'subscribe' and false signifies 'unsubscribe'. + +A node that sends the RPC with a filter request and `subscribe` set to 'true' +requests that the filter node SHOULD notify the light requesting node of messages +matching this filter. + +A node that sends the RPC with a filter request and `subscribe` set to 'false' +requests that the filter node SHOULD stop notifying the light requesting node +of messages matching this filter if it is currently doing so. + +The filter matches when content filter and, optionally, a topic is matched. +Content filter is matched when a `WakuMessage` `contentTopic` field is the same. + +A filter node SHOULD honor this request, though it MAY choose not to do so. If +it chooses not to do so it MAY tell the light why. The mechanism for doing this +is currently not specified. For notifying the light node a filter node sends a +MessagePush message. + +Since such a filter node is doing extra work for a light node, it MAY also +account for usage and be selective in how much service it provides. This +mechanism is currently planned but underspecified. + +#### MessagePush + +A filter node that has received a filter request SHOULD push all messages that +match this filter to a light node. These [`WakuMessage`'s](./waku-message.md) are likely to come from the +`relay` protocol and be kept at the Node, but there MAY be other sources or +protocols where this comes from. This is up to the consumer of the protocol. + +A filter node MUST NOT send a push message for messages that have not been +requested via a FilterRequest. + +If a specific light node isn't connected to a filter node for some specific +period of time (e.g. a TTL), then the filter node MAY choose to not push these +messages to the node. This period is up to the consumer of the protocol and node +implementation, though a reasonable default is one minute. + +--- +# Future Work + +**Anonymous filter subscription**: This feature guarantees that nodes can anonymously subscribe for a message filter (i.e., without revealing their exact content filter). As such, no adversary in the `WakuFilter` protocol would be able to link nodes to their subscribed content filers. The current version of the `WakuFilter` protocol does not provide anonymity as the subscribing node has a direct connection to the full node and explicitly submits its content filter to be notified about the matching messages. However, one can consider preserving anonymity through one of the following ways: +- By hiding the source of the subscription i.e., anonymous communication. That is the subscribing node shall hide all its PII in its filter request e.g., its IP address. This can happen by the utilization of a proxy server or by using Tor. + Note that the current structure of filter requests i.e., `FilterRPC` does not embody any piece of PII, otherwise, such data fields must be treated carefully to achieve anonymity. +- By deploying secure 2-party computations in which the subscribing node obtains the messages matching a content filter whereas the full node learns nothing about the content filter as well as the messages pushed to the subscribing node. Examples of such 2PC protocols are [Oblivious Transfers](https://link.springer.com/referenceworkentry/10.1007%2F978-1-4419-5906-5_9#:~:text=Oblivious%20transfer%20(OT)%20is%20a,information%20the%20receiver%20actually%20obtains.) and one-way Private Set Intersections (PSI). + +# Changelog + +### Next + +- Added initial threat model and security analysis. + +### 2.0.0-beta2 + +Initial draft version. Released [2020-10-28](https://github.com/vacp2p/specs/commit/5ceeb88cee7b918bb58f38e7c4de5d581ff31e68) +- Fix: Ensure contentFilter is a repeated field, on implementation +- Change: Add ability to unsubscribe from filters. Make `subscribe` an explicit boolean indication. Edit protobuf field order to be consistent with libp2p. + +### 2.0.0-beta1 + +Initial draft version. Released [2020-10-05](https://github.com/vacp2p/specs/commit/31857c7434fa17efc00e3cd648d90448797d107b) + +# Copyright + +Copyright and related rights waived via +[CC0](https://creativecommons.org/publicdomain/zero/1.0/). + +# References + +1. [Message Filtering (Wikipedia)](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern#Message_filtering) + +2. [Libp2p PubSub spec - topic validation](https://github.com/libp2p/specs/tree/master/pubsub#topic-validation) From d24b5890a1e61df77fd9c41d23530ce2cc890dd5 Mon Sep 17 00:00:00 2001 From: Hanno Cornelius Date: Wed, 26 Apr 2023 17:32:37 +0200 Subject: [PATCH 10/12] docs: try to repair yaml block --- content/docs/rfcs/12/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/rfcs/12/README.md b/content/docs/rfcs/12/README.md index dd7f679c1..d3212e42f 100644 --- a/content/docs/rfcs/12/README.md +++ b/content/docs/rfcs/12/README.md @@ -4,7 +4,7 @@ title: 12/WAKU2-FILTER name: Waku v2 Filter status: draft tags: waku-core -versions: [00](/spec/12/previous-versions/00/), 01 +versions: [00](/spec/12/previous-versions/00/) editor: Hanno Cornelius contributors: - Dean Eigenmann From 2c74eedfe4effbd157779a8fe13dde67fe16c58b Mon Sep 17 00:00:00 2001 From: Hanno Cornelius <68783915+jm-clius@users.noreply.github.com> Date: Wed, 26 Apr 2023 17:56:37 +0200 Subject: [PATCH 11/12] docs: another attempt to fix yaml block --- content/docs/rfcs/12/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/docs/rfcs/12/README.md b/content/docs/rfcs/12/README.md index d3212e42f..3f98ac6d8 100644 --- a/content/docs/rfcs/12/README.md +++ b/content/docs/rfcs/12/README.md @@ -4,7 +4,9 @@ title: 12/WAKU2-FILTER name: Waku v2 Filter status: draft tags: waku-core -versions: [00](/spec/12/previous-versions/00/) +versions: + - 00 + - 01 editor: Hanno Cornelius contributors: - Dean Eigenmann From cb35b9544ca2f42057bf105b6981aea86689fcc0 Mon Sep 17 00:00:00 2001 From: Hanno Cornelius Date: Tue, 2 May 2023 10:34:41 +0200 Subject: [PATCH 12/12] docs: new suggestion on how to use previous versions --- content/docs/rfcs/12/README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/content/docs/rfcs/12/README.md b/content/docs/rfcs/12/README.md index 3f98ac6d8..66078dca5 100644 --- a/content/docs/rfcs/12/README.md +++ b/content/docs/rfcs/12/README.md @@ -4,9 +4,7 @@ title: 12/WAKU2-FILTER name: Waku v2 Filter status: draft tags: waku-core -versions: - - 00 - - 01 +version: 01 editor: Hanno Cornelius contributors: - Dean Eigenmann @@ -15,6 +13,10 @@ contributors: - Ebube Ud --- +previous versions: [00](/spec/12/previous-versions/00/) + +--- + `WakuFilter` is a protocol that enables subscribing to messages that a peer receives. This is a more lightweight version of `WakuRelay` specifically designed for bandwidth restricted devices. This is due to the fact that light nodes subscribe to full-nodes and only receive the messages they desire. # Content filtering