From 05afd1897d4f0b90a3951dd2646779c7d0b9ce25 Mon Sep 17 00:00:00 2001 From: Oskar Thoren Date: Mon, 29 Mar 2021 16:59:17 +0800 Subject: [PATCH] 8/WAKU-MAIL: Import --- content/docs/rfcs/8/README.md | 125 ++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) diff --git a/content/docs/rfcs/8/README.md b/content/docs/rfcs/8/README.md index e69de29b..2ba32607 100644 --- a/content/docs/rfcs/8/README.md +++ b/content/docs/rfcs/8/README.md @@ -0,0 +1,125 @@ +--- +title: Waku Mailserver +version: 1.0.0 +status: Stable +authors: Adam Babik , Dean Eigenmann , Oskar Thorén +redirect_from: + - /waku/mailserver.html +--- + +## Table of Contents + +1. [Abstract](#abstract) +2. [Specification](#specification) + 1. [Requesting Historic Envelopes](#requesting-historic-envelopes) + 2. [Receiving Historic Envelopes](#receiving-historic-envelopes) + 3. [Security considerations](#security-considerations) +3. [Copyright](#copyright) + +## Abstract + +In this specification, we describe Mailservers. These are nodes responsible for archiving envelopes and delivering them to peers on-demand. + +## Specification + +A node which wants to provide mailserver functionality MUST store envelopes from incoming Messages packets (Waku packet-code `0x01`). The envelopes can be stored in any format, however they MUST be serialized and deserialized to the Waku envelope format. + +A mailserver SHOULD store envelopes for all topics to be generally useful for any peer, however for specific use cases it MAY store envelopes for a subset of topics. + +### Requesting Historic Envelopes + +In order to request historic envelopes, a node MUST send a packet P2P Request (`0x7e`) to a peer providing mailserver functionality. This packet requires one argument which MUST be a Waku envelope. + +In the Waku envelope's payload section, there MUST be RLP-encoded information about the details of the request: + +```abnf +; UNIX time in seconds; oldest requested envelope's creation time +lower = 4OCTET + +; UNIX time in seconds; newest requested envelope's creation time +upper = 4OCTET + +; array of Waku topics encoded in a bloom filter to filter envelopes +bloom = 64OCTET + +; unsigned integer limiting the number of returned envelopes +limit = 4OCTET + +; array of a cursor returned from the previous request (optional) +cursor = *OCTET + +; List of topics interested in +topics = "[" *1000topic "]" + +; 4 bytes of arbitrary data +topic = 4OCTET + +payload-without-topic = "[" lower upper bloom limit [ cursor ] "]" + +payload-with-topic = "[" lower upper bloom limit cursor [ topics ] "]" + +payload = payload-with-topic | payload-without-topic +``` + +The `Cursor` field SHOULD be filled in if a number of envelopes between `Lower` and `Upper` is greater than `Limit` so that the requester can send another request using the obtained `Cursor` value. What exactly is in the `Cursor` is up to the implementation. The requester SHOULD NOT use a `Cursor` obtained from one mailserver in a request to another mailserver because the format or the result MAY be different. + +The envelope MUST be encrypted with a symmetric key agreed between the requester and Mailserver. + +If `Topics` is used the `Cursor` field MUST be specified for the argument order to be unambiguous. However, it MAY be set to `null`. `Topics` is used to specify which topics a node is interested in. If `Topics` is not empty, a mailserver MUST only send envelopes that belong to a topic from `Topics` list and `Bloom` value MUST be ignored. + +### Receiving Historic Envelopes + +Historic envelopes MUST be sent to a peer as a packet with a P2P Message code (`0x7f`) followed by an array of Waku envelopes. A Mailserver MUST limit the amount of messages sent, either by the `Limit` specified in the request or limited to the maximum [RLPx packet size](./waku#maximum-packet-size), whichever limit comes first. + +In order to receive historic envelopes from a mailserver, a node MUST trust the selected mailserver, that is allow to receive expired packets with the P2P Message code. By default, such packets are discarded. + +Received envelopes MUST be passed through the Whisper envelope pipelines so that they are picked up by registered filters and passed to subscribers. + +For a requester, to know that all envelopes have been sent by mailserver, it SHOULD handle P2P Request Complete code (`0x7d`). This code is followed by a list with: + +```abnf +; array with a Keccak-256 hash of the envelope containing the original request. +request-id = 32OCTET + +; array with a Keccak-256 hash of the last sent envelope for the request. +last-envelope-hash = 32OCTET + +; array of a cursor returned from the previous request (optional) +cursor = *OCTET + +payload = "[" request-id last-envelope-hash [ cursor ] "]" +``` + +If `Cursor` is not empty, it means that not all envelopes were sent due to the set `Limit` in the request. One or more consecutive requests MAY be sent with `Cursor` field filled in in order to receive the rest of the envelopes. + +### Security considerations + +There are several security considerations to take into account when running or interacting with Mailservers. Chief among them are: scalability, DDoS-resistance and privacy. + +**Mailserver High Availability requirement:** + +A mailserver has to be online to receive envelopes for other nodes, this puts a high availability requirement on it. + +**Mailserver client privacy:** + +A mailserver client has to trust a mailserver, which means they can send direct traffic. This reveals what topics / bloom filter a node is interested in, along with its peerID (with IP). + +**Mailserver trusted connection:** + +A mailserver has a direct TCP connection, which means they are trusted to send traffic. This means a malicious or malfunctioning mailserver can overwhelm an individual node. + +## Changelog + +| Version | Comment | +| :--------------------------------------------------------------------------------------------: | ------- | +| [1.0.0](https://github.com/vacp2p/specs/commit/bc7e75ebb2e45d2cbf6ab27352c113e666df37c8) | marked stable as it is in use. | +| 0.2.0 | Add topic interest to reduce bandwidth usage | +| [0.1.0](https://github.com/vacp2p/specs/blob/06d4c736c920526472a507e5d842212843a112ed/wms.md) | Initial Release | + +### Difference between wms 0.1 and wms 0.2 + +- `topics` option + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).