mirror of https://github.com/status-im/specs.git
4 lines
21 KiB
HTML
4 lines
21 KiB
HTML
<!DOCTYPE html> <html lang="en-US"> <head> <meta charset="UTF-8"> <meta http-equiv="X-UA-Compatible" content="IE=Edge"> <title>11/WAKU-MAILSERVER - Status Specification</title> <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon"> <link rel="stylesheet" href="/assets/css/just-the-docs-default.css"> <script type="text/javascript" src="/assets/js/vendor/lunr.min.js"></script> <script type="text/javascript" src="/assets/js/just-the-docs.js"></script> <meta name="viewport" content="width=device-width, initial-scale=1"> <!-- Begin Jekyll SEO tag v2.7.1 --> <title>11/WAKU-MAILSERVER | Status Specification</title> <meta name="generator" content="Jekyll v4.2.1" /> <meta property="og:title" content="11/WAKU-MAILSERVER" /> <meta property="og:locale" content="en_US" /> <link rel="canonical" href="https://specs.status.im/spec/11" /> <meta property="og:url" content="https://specs.status.im/spec/11" /> <meta property="og:site_name" content="Status Specification" /> <meta name="twitter:card" content="summary" /> <meta property="twitter:title" content="11/WAKU-MAILSERVER" /> <script type="application/ld+json"> {"@type":"WebPage","url":"https://specs.status.im/spec/11","headline":"11/WAKU-MAILSERVER","@context":"https://schema.org"}</script> <!-- End Jekyll SEO tag --> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-link" viewBox="0 0 24 24"> <title>Link</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"> <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path> </svg> </symbol> <symbol id="svg-search" viewBox="0 0 24 24"> <title>Search</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-search"> <circle cx="11" cy="11" r="8"></circle><line x1="21" y1="21" x2="16.65" y2="16.65"></line> </svg> </symbol> <symbol id="svg-menu" viewBox="0 0 24 24"> <title>Menu</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-menu"> <line x1="3" y1="12" x2="21" y2="12"></line><line x1="3" y1="6" x2="21" y2="6"></line><line x1="3" y1="18" x2="21" y2="18"></line> </svg> </symbol> <symbol id="svg-arrow-right" viewBox="0 0 24 24"> <title>Expand</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-chevron-right"> <polyline points="9 18 15 12 9 6"></polyline> </svg> </symbol> <symbol id="svg-doc" viewBox="0 0 24 24"> <title>Document</title> <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-file"> <path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"></path><polyline points="13 2 13 9 20 9"></polyline> </svg> </symbol> </svg> <div class="side-bar"> <div class="site-header"> <a href="https://specs.status.im/" class="site-title lh-tight"> Status Specification </a> <a href="#" id="menu-button" class="site-button"> <svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-menu"></use></svg> </a> </div> <nav role="navigation" aria-label="Main" id="site-nav" class="site-nav"> <ul class="nav-list"><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="https://specs.status.im/spec/" class="nav-list-link">Stable specs</a><ul class="nav-list "><li class="nav-list-item "><a href="https://specs.status.im/spec/1" class="nav-list-link">1/CLIENT</a></li><li class="nav-list-item "><a href="https://specs.status.im/spec/10" class="nav-list-link">10/WAKU-USAGE</a></li><li class="nav-list-item active"><a href="https://specs.status.im/spec/11" class="nav-list-link active">11/WAKU-MAILSERVER</a></li><li class="nav-list-item "><a href="https://specs.status.im/spec/15" class="nav-list-link">15/NOTIFICATIONS</a></li><li class="nav-list-item "><a href="https://specs.status.im/spec/2" class="nav-list-link">2/ACCOUNT</a></li><li class="nav-list-item "><a href="https://specs.status.im/spec/3" class="nav-list-link">3/WHISPER-USAGE</a></li><li class="nav-list-item "><a href="https://specs.status.im/spec/4" class="nav-list-link">4/WHISPER-MAILSERVER</a></li><li class="nav-list-item "><a href="https://specs.status.im/spec/5" class="nav-list-link">5/SECURE-TRANSPORT</a></li><li class="nav-list-item "><a href="https://specs.status.im/spec/6" class="nav-list-link">6/PAYLOADS</a></li><li class="nav-list-item "><a href="https://specs.status.im/spec/8" class="nav-list-link">8/EIPS</a></li><li class="nav-list-item "><a href="https://specs.status.im/spec/9" class="nav-list-link">9/ETHEREUM-USAGE</a></li></ul></li><li class="nav-list-item"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="https://specs.status.im/draft/" class="nav-list-link">Draft specs</a><ul class="nav-list "><li class="nav-list-item "><a href="https://specs.status.im/draft/12" class="nav-list-link">12/IPFS gateway for Sticker Pack</a></li><li class="nav-list-item "><a href="https://specs.status.im/draft/13" class="nav-list-link">13/3RD-PARTY-USAGE</a></li><li class="nav-list-item "><a href="https://specs.status.im/draft/14" class="nav-list-link">14/Dapp browser API usage</a></li><li class="nav-list-item "><a href="https://specs.status.im/draft/16" class="nav-list-link">16/Keycard Usage for Wallet and Chat Keys</a></li><li class="nav-list-item "><a href="https://specs.status.im/draft/3" class="nav-list-link">3/WHISPER-USAGE</a></li><li class="nav-list-item "><a href="https://specs.status.im/draft/6" class="nav-list-link">6/PAYLOADS</a></li><li class="nav-list-item "><a href="https://specs.status.im/draft/7" class="nav-list-link">7/GROUP-CHAT</a></li></ul></li><li class="nav-list-item"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="https://specs.status.im/raw/" class="nav-list-link">Raw specs</a><ul class="nav-list "><li class="nav-list-item "><a href="https://specs.status.im/raw/16" class="nav-list-link">16/PUSH-NOTIFICATION-SERVER</a></li></ul></li><li class="nav-list-item"><a href="https://specs.status.im/development" class="nav-list-link">DEVELOPMENT</a></li><li class="nav-list-item"><a href="https://specs.status.im/style-guideline" class="nav-list-link">STYLE-GUIDELINE</a></li></ul> </nav> <footer class="site-footer"> This site uses <a href="https://github.com/pmarsceill/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll. </footer> </div> <div class="main" id="top"> <div id="main-header" class="main-header"> <div class="search"> <div class="search-input-wrap"> <input type="text" id="search-input" class="search-input" tabindex="0" placeholder="Search Status Specification" aria-label="Search Status Specification" autocomplete="off"> <label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#svg-search"></use></svg></label> </div> <div id="search-results" class="search-results"></div> </div> </div> <div id="main-content-wrap" class="main-content-wrap"> <nav aria-label="Breadcrumb" class="breadcrumb-nav"> <ol class="breadcrumb-nav-list"> <li class="breadcrumb-nav-list-item"><a href="https://specs.status.im/spec/">Stable specs</a></li> <li class="breadcrumb-nav-list-item"><span>11/WAKU-MAILSERVER</span></li> </ol> </nav> <div id="main-content" class="main-content" role="main"> <h1 id="11waku-mailserver"> <a href="#11waku-mailserver" class="anchor-heading" aria-labelledby="11waku-mailserver"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> 11/WAKU-MAILSERVER </h1> <blockquote> <p>Version: 0.1</p> <p>Status: Stable</p> <p>Authors: Adam Babik <a href="mailto:adam@status.im">adam@status.im</a>, Oskar Thorén <a href="mailto:oskar@status.im">oskar@status.im</a>, Samuel Hawksby-Robinson <a href="mailto:samuel@status.im">samuel@status.im</a> (alphabetical order)</p> </blockquote> <ul> <li><a href="#11waku-mailserver">Status Waku Mailserver Specification</a> <ul> <li><a href="#abstract">Abstract</a></li> <li><a href="#mailserver"><code class="language-plaintext highlighter-rouge">Mailserver</code></a> <ul> <li><a href="#archiving-messages">Archiving messages</a></li> <li><a href="#requesting-messages">Requesting messages</a></li> <li><a href="#receiving-historic-messages">Receiving historic messages</a></li> </ul> </li> <li><a href="#security-considerations">Security considerations</a> <ul> <li><a href="#confidentiality">Confidentiality</a></li> <li><a href="#altruistic-and-centralized-operator-risk">Altruistic and centralized operator risk</a></li> <li><a href="#privacy-concerns">Privacy concerns</a></li> <li><a href="#denial-of-service">Denial-of-service</a></li> </ul> </li> <li><a href="#changelog">Changelog</a> <ul> <li><a href="#version-01">Version 0.1</a></li> </ul> </li> </ul> </li> </ul> <h2 id="abstract"> <a href="#abstract" class="anchor-heading" aria-labelledby="abstract"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Abstract </h2> <p>Being mostly offline is an intrinsic property of mobile clients. They need to save network transfer and battery consumption to avoid spending too much money or constant charging. Waku protocol, on the other hand, is an online protocol. Messages are available in the Waku network only for short period of time calculate in seconds.</p> <p>Waku Mailserver is a specification that allows messages to be stored permanently and to allows the stored messages to be delivered to requesting client nodes, regardless if the messages are not available in the network due to the message TTL expiring.</p> <h2 id="mailserver"> <a href="#mailserver" class="anchor-heading" aria-labelledby="mailserver"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> <code class="language-plaintext highlighter-rouge">Mailserver</code> </h2> <p>From the network perspective, a <code class="language-plaintext highlighter-rouge">Mailserver</code> is just like any other Waku node. The only difference is that a <code class="language-plaintext highlighter-rouge">Mailserver</code> has the capability of archiving messages and delivering them to its peers on-demand.</p> <p>It is important to notice that a <code class="language-plaintext highlighter-rouge">Mailserver</code> will only handle requests from its direct peers and exchanged packets between a <code class="language-plaintext highlighter-rouge">Mailserver</code> and a peer are p2p messages.</p> <h3 id="archiving-messages"> <a href="#archiving-messages" class="anchor-heading" aria-labelledby="archiving-messages"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Archiving messages </h3> <p>A node which wants to provide <code class="language-plaintext highlighter-rouge">Mailserver</code> functionality MUST store envelopes from incoming message packets (Waku packet-code <code class="language-plaintext highlighter-rouge">0x01</code>). The envelopes can be stored in any format, however they MUST be serialized and deserialized to the Waku envelope format.</p> <p>A <code class="language-plaintext highlighter-rouge">Mailserver</code> 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.</p> <h3 id="requesting-messages"> <a href="#requesting-messages" class="anchor-heading" aria-labelledby="requesting-messages"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Requesting messages </h3> <p>In order to request historic messages, a node MUST send a packet P2P Request (<code class="language-plaintext highlighter-rouge">0x7e</code>) to a peer providing <code class="language-plaintext highlighter-rouge">Mailserver</code> functionality. This packet requires one argument which MUST be a Waku envelope.</p> <p>In the Waku envelope’s payload section, there MUST be RLP-encoded information about the details of the request:</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>[ Lower, Upper, Bloom, Limit, Cursor ]
|
||
</code></pre></div></div> <p><code class="language-plaintext highlighter-rouge">Lower</code>: 4-byte wide unsigned integer (UNIX time in seconds; oldest requested envelope’s creation time)<br /> <code class="language-plaintext highlighter-rouge">Upper</code>: 4-byte wide unsigned integer (UNIX time in seconds; newest requested envelope’s creation time)<br /> <code class="language-plaintext highlighter-rouge">Bloom</code>: 64-byte wide array of Waku topics encoded in a bloom filter to filter envelopes<br /> <code class="language-plaintext highlighter-rouge">Limit</code>: 4-byte wide unsigned integer limiting the number of returned envelopes<br /> <code class="language-plaintext highlighter-rouge">Cursor</code>: an array of a cursor returned from the previous request (optional)</p> <p>The <code class="language-plaintext highlighter-rouge">Cursor</code> field SHOULD be filled in if a number of envelopes between <code class="language-plaintext highlighter-rouge">Lower</code> and <code class="language-plaintext highlighter-rouge">Upper</code> is greater than <code class="language-plaintext highlighter-rouge">Limit</code> so that the requester can send another request using the obtained <code class="language-plaintext highlighter-rouge">Cursor</code> value. What exactly is in the <code class="language-plaintext highlighter-rouge">Cursor</code> is up to the implementation. The requester SHOULD NOT use a <code class="language-plaintext highlighter-rouge">Cursor</code> obtained from one <code class="language-plaintext highlighter-rouge">Mailserver</code> in a request to another <code class="language-plaintext highlighter-rouge">Mailserver</code> because the format or the result MAY be different.</p> <p>The envelope MUST be encrypted with a symmetric key agreed between the requester and the <code class="language-plaintext highlighter-rouge">Mailserver</code>.</p> <h3 id="receiving-historic-messages"> <a href="#receiving-historic-messages" class="anchor-heading" aria-labelledby="receiving-historic-messages"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Receiving historic messages </h3> <p>Historic messages MUST be sent to a peer as a packet with a P2P Message code (<code class="language-plaintext highlighter-rouge">0x7f</code>) followed by an array of Waku envelopes.</p> <p>In order to receive historic messages from a <code class="language-plaintext highlighter-rouge">Mailserver</code>, a node MUST trust the selected <code class="language-plaintext highlighter-rouge">Mailserver</code>, that is allowed to send packets with the P2P Message code. By default, the node discards such packets.</p> <p>Received envelopes MUST be passed through the Waku envelope pipelines so that they are picked up by registered filters and passed to subscribers.</p> <p>For a requester, to know that all messages have been sent by a <code class="language-plaintext highlighter-rouge">Mailserver</code>, it SHOULD handle P2P Request Complete code (<code class="language-plaintext highlighter-rouge">0x7d</code>). This code is followed by the following parameters:</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>[ RequestID, LastEnvelopeHash, Cursor ]
|
||
</code></pre></div></div> <ul> <li><code class="language-plaintext highlighter-rouge">RequestID</code>: 32-byte wide array with a Keccak-256 hash of the envelope containing the original request</li> <li><code class="language-plaintext highlighter-rouge">LastEnvelopeHash</code>: 32-byte wide array with a Keccak-256 hash of the last sent envelope for the request</li> <li><code class="language-plaintext highlighter-rouge">Cursor</code>: an array of a cursor returned from the previous request (optional)</li> </ul> <p>If <code class="language-plaintext highlighter-rouge">Cursor</code> is not empty, it means that not all messages were sent due to the set <code class="language-plaintext highlighter-rouge">Limit</code> in the request. One or more consecutive requests MAY be sent with <code class="language-plaintext highlighter-rouge">Cursor</code> field filled in order to receive the rest of the messages.</p> <h2 id="security-considerations"> <a href="#security-considerations" class="anchor-heading" aria-labelledby="security-considerations"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Security considerations </h2> <h3 id="confidentiality"> <a href="#confidentiality" class="anchor-heading" aria-labelledby="confidentiality"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Confidentiality </h3> <p>The node encrypts all Waku envelopes. A <code class="language-plaintext highlighter-rouge">Mailserver</code> node can not inspect their contents.</p> <h3 id="altruistic-and-centralized-operator-risk"> <a href="#altruistic-and-centralized-operator-risk" class="anchor-heading" aria-labelledby="altruistic-and-centralized-operator-risk"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Altruistic and centralized operator risk </h3> <p>In order to be useful, a <code class="language-plaintext highlighter-rouge">Mailserver</code> SHOULD be online most of time. That means users either have to be a bit tech-savvy to run their own node, or rely on someone else to run it for them.</p> <p>Currently, one of Status’s legal entities provides <code class="language-plaintext highlighter-rouge">Mailservers</code> in an altruistic manner, but this is suboptimal from a decentralization, continuance and risk point of view. Coming up with a better system for this is ongoing research.</p> <p>A Status client SHOULD allow the <code class="language-plaintext highlighter-rouge">Mailserver</code> selection to be customizable.</p> <h3 id="privacy-concerns"> <a href="#privacy-concerns" class="anchor-heading" aria-labelledby="privacy-concerns"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Privacy concerns </h3> <p>In order to use a <code class="language-plaintext highlighter-rouge">Mailserver</code>, a given node needs to connect to it directly, i.e. add the <code class="language-plaintext highlighter-rouge">Mailserver</code> as its peer and mark it as trusted. This means that the <code class="language-plaintext highlighter-rouge">Mailserver</code> is able to send direct p2p messages to the node instead of broadcasting them. Effectively, it will have access to the bloom filter of topics that the user is interested in, when it is online as well as many metadata like IP address.</p> <h3 id="denial-of-service"> <a href="#denial-of-service" class="anchor-heading" aria-labelledby="denial-of-service"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Denial-of-service </h3> <p>Since a <code class="language-plaintext highlighter-rouge">Mailserver</code> is delivering expired envelopes and has a direct TCP connection with the recipient, the recipient is vulnerable to DoS attacks from a malicious <code class="language-plaintext highlighter-rouge">Mailserver</code> node.</p> <h2 id="changelog"> <a href="#changelog" class="anchor-heading" aria-labelledby="changelog"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Changelog </h2> <h3 id="version-01"> <a href="#version-01" class="anchor-heading" aria-labelledby="version-01"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Version 0.1 </h3> <p>Released <a href="https://github.com/status-im/specs/commit/664dd1c9df6ad409e4c007fefc8c8945b8d324e8">May 22, 2020</a></p> <ul> <li>Created document</li> <li>Forked from <a href="4-whisper-mailserver.md">4-whisper-mailserver</a></li> <li>Change to keep <code class="language-plaintext highlighter-rouge">Mailserver</code> term consistent</li> <li>Replaced Whisper references with Waku</li> </ul> <h2 id="copyright"> <a href="#copyright" class="anchor-heading" aria-labelledby="copyright"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Copyright </h2> <p>Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p> </div> </div> <div class="search-overlay"></div> </div> </body> </html>
|