mirror of https://github.com/vacp2p/rfc.git
452 lines
18 KiB
HTML
452 lines
18 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en" dir="ltr">
|
||
|
||
<head>
|
||
<meta name="generator" content="Hugo 0.106.0">
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="description" content="Abstract # Waku v2 is a family of modular peer-to-peer protocols for secure communication. These protocols are designed to be secure, privacy-preserving, and censorship-resistant and can run in resource-restricted environments. At a high level, Waku v2 implements a Pub/Sub messaging pattern over libp2p and adds capabilities.
|
||
The present document specifies the Waku v2 message format, a way to encapsulate the messages sent with specific information security goals, and Whisper/Waku v1 backward compatibility.">
|
||
<meta name="theme-color" content="#FFFFFF"><meta property="og:title" content="14/WAKU2-MESSAGE" />
|
||
<meta property="og:description" content="Abstract # Waku v2 is a family of modular peer-to-peer protocols for secure communication. These protocols are designed to be secure, privacy-preserving, and censorship-resistant and can run in resource-restricted environments. At a high level, Waku v2 implements a Pub/Sub messaging pattern over libp2p and adds capabilities.
|
||
The present document specifies the Waku v2 message format, a way to encapsulate the messages sent with specific information security goals, and Whisper/Waku v1 backward compatibility." />
|
||
<meta property="og:type" content="article" />
|
||
<meta property="og:url" content="https://rfc.vac.dev/spec/14/" /><meta property="article:section" content="docs" />
|
||
|
||
|
||
|
||
<title>14/WAKU2-MESSAGE | Vac RFC</title>
|
||
<link rel="manifest" href="/manifest.json">
|
||
<link rel="icon" href="/favicon.png" type="image/x-icon">
|
||
<link rel="stylesheet" href="/book.min.e935e20bd0d469378cb482f0958edf258c731a4f895dccd55799c6fbc8043f23.css" integrity="sha256-6TXiC9DUaTeMtILwlY7fJYxzGk+JXczVV5nG+8gEPyM=">
|
||
<script defer src="/en.search.min.06839260bd3cd325ccc30b304a33015b3262511616f3b07ba00bf537143fcbfb.js" integrity="sha256-BoOSYL080yXMwwswSjMBWzJiURYW87B7oAv1NxQ/y/s="></script>
|
||
<!--
|
||
Made with Book Theme
|
||
https://github.com/alex-shpak/hugo-book
|
||
-->
|
||
|
||
|
||
</head>
|
||
|
||
<body dir="ltr">
|
||
<input type="checkbox" class="hidden toggle" id="menu-control" />
|
||
<input type="checkbox" class="hidden toggle" id="toc-control" />
|
||
<main class="container flex">
|
||
<aside class="book-menu">
|
||
<div class="book-menu-content">
|
||
|
||
<nav>
|
||
<h2 class="book-brand">
|
||
<a href="/"><span>Vac RFC</span>
|
||
</a>
|
||
</h2>
|
||
|
||
|
||
<div class="book-search">
|
||
<input type="text" id="book-search-input" placeholder="Search" aria-label="Search" maxlength="64" data-hotkeys="s/" />
|
||
<div class="book-search-spinner hidden"></div>
|
||
<ul id="book-search-results"></ul>
|
||
</div>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<ul>
|
||
<li>Raw
|
||
<ul>
|
||
<li><a href="/spec/20/">20/TOY-ETH-PM</a></li>
|
||
<li><a href="/spec/24/">24/STATUS-CURATION</a></li>
|
||
<li><a href="/spec/28/">28/STATUS-FEATURING</a></li>
|
||
<li><a href="/spec/31/">31/WAKU2-ENR</a></li>
|
||
<li><a href="/spec/32/">32/RLN-SPEC</a></li>
|
||
<li><a href="/spec/34/">34/WAKU2-PEER-EXCHANGE</a></li>
|
||
<li><a href="/spec/35/">35/WAKU2-NOISE</a></li>
|
||
<li><a href="/spec/37/">37/WAKU2-NOISE-SESSIONS</a></li>
|
||
<li><a href="/spec/43/">43/WAKU2-NOISE-PAIRING</a></li>
|
||
<li><a href="/spec/44/">44/WAKU2-DANDELION</a></li>
|
||
<li><a href="/spec/45/">45/WAKU2-ADVERSARIAL-MODELS</a></li>
|
||
<li><a href="/spec/46/">46/GOSSIPSUB-TOR-PUSH</a></li>
|
||
<li><a href="/spec/47/">47/WAKU2-TOR-PUSH</a></li>
|
||
</ul>
|
||
</li>
|
||
<li>Draft
|
||
<ul>
|
||
<li><a href="/spec/1/">1/COSS</a></li>
|
||
<li><a href="/spec/3/">3/REMOTE-LOG</a></li>
|
||
<li><a href="/spec/4/">4/MVDS-META</a></li>
|
||
<li><a href="/spec/10/">10/WAKU2</a></li>
|
||
<li><a href="/spec/12/">12/WAKU2-FILTER</a></li>
|
||
<li><a href="/spec/13/">13/WAKU2-STORE</a></li>
|
||
<li><a href="/spec/14/"class=active>14/WAKU2-MESSAGE</a></li>
|
||
<li><a href="/spec/15/">15/WAKU2-BRIDGE</a></li>
|
||
<li><a href="/spec/16/">16/WAKU2-RPC</a></li>
|
||
<li><a href="/spec/17/">17/WAKU2-RLN-RELAY</a></li>
|
||
<li><a href="/spec/18/">18/WAKU2-SWAP</a></li>
|
||
<li><a href="/spec/19/">19/WAKU2-LIGHTPUSH</a></li>
|
||
<li><a href="/spec/21/">21/WAKU2-FTSTORE</a></li>
|
||
<li><a href="/spec/22/">22/TOY-CHAT</a></li>
|
||
<li><a href="/spec/23/">23/WAKU2-TOPICS</a></li>
|
||
<li><a href="/spec/26/">26/WAKU2-PAYLOAD</a></li>
|
||
<li><a href="/spec/27/">27/WAKU2-PEERS</a></li>
|
||
<li><a href="/spec/29/">29/WAKU2-CONFIG</a></li>
|
||
<li><a href="/spec/30/">30/ADAPTIVE-NODES</a></li>
|
||
<li><a href="/spec/33/">33/WAKU2-DISCV5</a></li>
|
||
<li><a href="/spec/36/">36/WAKU2-BINDINGS-API</a></li>
|
||
</ul>
|
||
</li>
|
||
<li>Stable
|
||
<ul>
|
||
<li><a href="/spec/2/">2/MVDS</a></li>
|
||
<li><a href="/spec/6/">6/WAKU1</a></li>
|
||
<li><a href="/spec/7/">7/WAKU-DATA</a></li>
|
||
<li><a href="/spec/8/">8/WAKU-MAIL</a></li>
|
||
<li><a href="/spec/9/">9/WAKU-RPC</a></li>
|
||
<li><a href="/spec/11/">11/WAKU2-RELAY</a></li>
|
||
</ul>
|
||
</li>
|
||
<li>Deprecated
|
||
<ul>
|
||
<li><a href="/spec/5/">5/WAKU0</a></li>
|
||
</ul>
|
||
</li>
|
||
<li>Retired</li>
|
||
</ul>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</nav>
|
||
|
||
|
||
|
||
|
||
<script>(function(){var e=document.querySelector("aside.book-menu nav");addEventListener("beforeunload",function(){localStorage.setItem("menu.scrollTop",e.scrollTop)}),e.scrollTop=localStorage.getItem("menu.scrollTop")})()</script>
|
||
|
||
|
||
|
||
</div>
|
||
</aside>
|
||
|
||
<div class="book-page">
|
||
<header class="book-header">
|
||
|
||
<div class="flex align-center justify-between">
|
||
<label for="menu-control">
|
||
<img src="/svg/menu.svg" class="book-icon" alt="Menu" />
|
||
</label>
|
||
|
||
<strong>14/WAKU2-MESSAGE</strong>
|
||
|
||
<label for="toc-control">
|
||
|
||
<img src="/svg/toc.svg" class="book-icon" alt="Table of Contents" />
|
||
|
||
</label>
|
||
</div>
|
||
|
||
|
||
|
||
<aside class="hidden clearfix">
|
||
|
||
|
||
<nav id="TableOfContents">
|
||
<ul>
|
||
<li><a href="#waku-message">Waku Message</a></li>
|
||
<li><a href="#message-attributes">Message Attributes</a></li>
|
||
</ul>
|
||
|
||
<ul>
|
||
<li><a href="#confidentiality-integrity-and-authenticity">Confidentiality, integrity, and authenticity</a></li>
|
||
<li><a href="#reliability-of-the-timestamp-attribute">Reliability of the <code>timestamp</code> attribute</a></li>
|
||
<li><a href="#reliability-of-the-ephemeral-attribute">Reliability of the <code>ephemeral</code> attribute</a></li>
|
||
<li><a href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
</nav>
|
||
|
||
|
||
|
||
</aside>
|
||
|
||
|
||
</header>
|
||
|
||
|
||
|
||
<article class="markdown">
|
||
<h1 id="14waku2-message">
|
||
14/WAKU2-MESSAGE
|
||
<a class="anchor" href="#14waku2-message">#</a>
|
||
</h1>
|
||
|
||
|
||
<h1 id="waku-v2-message">
|
||
Waku v2 Message
|
||
<a class="anchor" href="#waku-v2-message">#</a>
|
||
</h1>
|
||
|
||
|
||
|
||
|
||
|
||
<img src="https://img.shields.io/badge/status-draft-blue?style=flat-square" />
|
||
|
||
|
||
|
||
|
||
|
||
<ul>
|
||
<li>Status: draft</li>
|
||
<li>Editor: Oskar Thorén <a href="mailto:oskar@status.im">oskar@status.im</a></li>
|
||
|
||
<li>Contributors:
|
||
|
||
|
||
Sanaz Taheri <a href="mailto:sanaz@status.im">sanaz@status.im</a>
|
||
|
||
,
|
||
Aaryamann Challani <a href="mailto:aaryamann@status.im">aaryamann@status.im</a>
|
||
|
||
,
|
||
Lorenzo Delgado <a href="mailto:lorenzo@status.im">lorenzo@status.im</a>
|
||
|
||
</li>
|
||
|
||
</ul><h1 id="abstract">
|
||
Abstract
|
||
<a class="anchor" href="#abstract">#</a>
|
||
</h1>
|
||
<p>Waku v2 is a family of modular peer-to-peer protocols for secure communication.
|
||
These protocols are designed to be secure, privacy-preserving, and censorship-resistant and can run in resource-restricted environments.
|
||
At a high level, Waku v2 implements a Pub/Sub messaging pattern over libp2p and adds capabilities.</p>
|
||
<p>The present document specifies the Waku v2 message format, a way to encapsulate the messages sent with specific information security goals, and Whisper/Waku v1 backward compatibility.</p>
|
||
<h1 id="motivation">
|
||
Motivation
|
||
<a class="anchor" href="#motivation">#</a>
|
||
</h1>
|
||
<p>When sending messages over Waku, there are multiple requirements:</p>
|
||
<ul>
|
||
<li>One may have a separate encryption layer as part of the application.</li>
|
||
<li>One may want to provide efficient routing for resource-restricted devices.</li>
|
||
<li>One may want to provide compatibility with <a href="/spec/6/">Waku v1 envelopes</a>.</li>
|
||
<li>One may want encrypted payloads by default.</li>
|
||
<li>One may want to provide unlinkability to get metadata protection.</li>
|
||
</ul>
|
||
<p>This specification attempts to provide for these various requirements.</p>
|
||
<h1 id="semantics">
|
||
Semantics
|
||
<a class="anchor" href="#semantics">#</a>
|
||
</h1>
|
||
<h2 id="waku-message">
|
||
Waku Message
|
||
<a class="anchor" href="#waku-message">#</a>
|
||
</h2>
|
||
<p>A Waku message is constituted by the combination of data payload and attributes that, for example, a <em>publisher</em> sends to a <em>topic</em> and is eventually delivered to <em>subscribers</em>.</p>
|
||
<p>Waku message attributes are key-value pairs of metadata associated with a message.
|
||
And the message data payload is the part of the transmitted Waku message that is the actual message information.
|
||
The data payload is also treated as a Waku message attribute for convenience.</p>
|
||
<h2 id="message-attributes">
|
||
Message Attributes
|
||
<a class="anchor" href="#message-attributes">#</a>
|
||
</h2>
|
||
<ul>
|
||
<li>
|
||
<p>The <code>payload</code> attribute MUST contain the message data payload to be sent.</p>
|
||
</li>
|
||
<li>
|
||
<p>The <code>content_topic</code> attribute MUST specify a string identifier that can be used for content-based filtering.</p>
|
||
</li>
|
||
<li>
|
||
<p>The <code>version</code> attribute, if present, contains a version number to discriminate different types of payload encryption.
|
||
If omitted, the value SHOULD be interpreted as version 0.</p>
|
||
</li>
|
||
<li>
|
||
<p>The <code>timestamp</code> attribute, if present, signifies the time at which the message was generated by its sender.
|
||
This attribute MAY contain the Unix epoch time in nanoseconds.
|
||
If the attribute is omitted, it SHOULD be interpreted as timestamp 0.</p>
|
||
</li>
|
||
<li>
|
||
<p>The <code>ephemeral</code> attribute, if present, signifies the transient nature of the message.
|
||
For example, an ephemeral message SHOULD not be persisted by the Waku network.
|
||
If this attribute is set to <code>true</code>, the message SHOULD be interpreted as ephemeral.
|
||
If, instead, the attribute is omitted or set to <code>false</code>, the message SHOULD be interpreted as non-ephemeral.</p>
|
||
</li>
|
||
</ul>
|
||
<h1 id="wire-format">
|
||
Wire Format
|
||
<a class="anchor" href="#wire-format">#</a>
|
||
</h1>
|
||
<p>The Waku message wire format is specified using <a href="https://developers.google.com/protocol-buffers/">protocol buffers v3</a>.</p>
|
||
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-protobuf" data-lang="protobuf"><span style="display:flex;"><span>syntax <span style="color:#f92672">=</span> <span style="color:#e6db74">"proto3"</span>;<span style="color:#960050;background-color:#1e0010">
|
||
</span></span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010">
|
||
</span></span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010"></span><span style="color:#66d9ef">message</span> <span style="color:#a6e22e">WakuMessage</span> {<span style="color:#960050;background-color:#1e0010">
|
||
</span></span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010"></span> <span style="color:#66d9ef">bytes</span> payload <span style="color:#f92672">=</span> <span style="color:#ae81ff">1</span>;<span style="color:#960050;background-color:#1e0010">
|
||
</span></span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010"></span> <span style="color:#66d9ef">string</span> content_topic <span style="color:#f92672">=</span> <span style="color:#ae81ff">2</span>;<span style="color:#960050;background-color:#1e0010">
|
||
</span></span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010"></span> <span style="color:#66d9ef">optional</span> <span style="color:#66d9ef">uint32</span> version <span style="color:#f92672">=</span> <span style="color:#ae81ff">3</span>;<span style="color:#960050;background-color:#1e0010">
|
||
</span></span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010"></span> <span style="color:#66d9ef">optional</span> <span style="color:#66d9ef">sint64</span> timestamp <span style="color:#f92672">=</span> <span style="color:#ae81ff">10</span>;<span style="color:#960050;background-color:#1e0010">
|
||
</span></span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010"></span> <span style="color:#66d9ef">optional</span> <span style="color:#66d9ef">bool</span> ephemeral <span style="color:#f92672">=</span> <span style="color:#ae81ff">31</span>;<span style="color:#960050;background-color:#1e0010">
|
||
</span></span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010"></span>}<span style="color:#960050;background-color:#1e0010">
|
||
</span></span></span></code></pre></div><h1 id="payload-encryption">
|
||
Payload encryption
|
||
<a class="anchor" href="#payload-encryption">#</a>
|
||
</h1>
|
||
<p>The Waku message payload MAY be encrypted.
|
||
The message <code>version</code> attribute indicates the schema used to encrypt the payload data.</p>
|
||
<ul>
|
||
<li>
|
||
<p><strong>Version 0:</strong>
|
||
The payload SHOULD be interpreted as unencrypted; additionally, it CAN indicate that the message payload has been encrypted at the application layer.</p>
|
||
</li>
|
||
<li>
|
||
<p><strong>Version 1:</strong>
|
||
The payload SHOULD be encrypted using Waku v1 payload encryption specified in <a href="/spec/26">26/WAKU-PAYLOAD</a>.
|
||
This provides asymmetric and symmetric encryption.
|
||
The key agreement is performed out of band.
|
||
And provides an encrypted signature and padding for some form of unlinkability.</p>
|
||
</li>
|
||
<li>
|
||
<p><strong>Version 2:</strong>
|
||
The payload SHOULD be encoded according to <a href="/spec/35">35/WAKU2-NOISE</a>.
|
||
Waku Noise protocol provides symmetric encryption and asymmetric key exchange.</p>
|
||
</li>
|
||
</ul>
|
||
<p>Any <code>version</code> value not included in this list is reserved for future specification.
|
||
And, in this case, the payload SHOULD be interpreted as unencrypted by the Waku layer.</p>
|
||
<h1 id="whisperwaku-v1-envelope-compatibility">
|
||
Whisper/Waku v1 envelope compatibility
|
||
<a class="anchor" href="#whisperwaku-v1-envelope-compatibility">#</a>
|
||
</h1>
|
||
<p>Whisper/Waku v1 envelopes are compatible with Waku v2 messages format.</p>
|
||
<ul>
|
||
<li>Whisper/Waku v1 <code>topic</code> field SHOULD be mapped to Waku v2 message’s <code>content_topic</code> attribute.</li>
|
||
<li>Whisper/Waku v1 <code>data</code> field SHOULD be mapped to Waku v2 message’s <code>payload</code> attribute.</li>
|
||
</ul>
|
||
<p>Waku v2 implements a pub/sub messaging pattern over libp2p.
|
||
This makes redundant some Whisper/Waku v1 envelope fields (e.g., <code>expiry</code>, <code>ttl</code>, <code>topic</code>, etc.), so they can be ignored.</p>
|
||
<h1 id="security-considerations">
|
||
Security Considerations
|
||
<a class="anchor" href="#security-considerations">#</a>
|
||
</h1>
|
||
<h2 id="confidentiality-integrity-and-authenticity">
|
||
Confidentiality, integrity, and authenticity
|
||
<a class="anchor" href="#confidentiality-integrity-and-authenticity">#</a>
|
||
</h2>
|
||
<p>The level of confidentiality, integrity, and authenticity of the Waku message payload is discretionary.
|
||
Accordingly, the application layer shall utilize the encryption and signature schemes supported by Waku v2 to meet the application-specific privacy needs.</p>
|
||
<h2 id="reliability-of-the-timestamp-attribute">
|
||
Reliability of the <code>timestamp</code> attribute
|
||
<a class="anchor" href="#reliability-of-the-timestamp-attribute">#</a>
|
||
</h2>
|
||
<p>The Waku message <code>timestamp</code> attribute is set by the sender.
|
||
Therefore, because message timestamps aren’t independently verified, this attribute is prone to exploitation and misuse.
|
||
It should not solely be relied upon for operations such as message ordering.
|
||
For example, a malicious actor can arbitrarily set the <code>timestamp</code> of a Waku message to a high value so that it always shows up as the most recent message in a chat application.
|
||
Applications using Waku messages’ <code>timestamp</code> attribute are recommended to use additional methods for more robust message ordering.
|
||
An example of how to deal with message ordering against adversarial message timestamps can be found in the Status protocol, see <a href="https://specs.status.im/spec/6#clock-vs-timestamp-and-message-ordering">6/PAYLOADS</a>.</p>
|
||
<h2 id="reliability-of-the-ephemeral-attribute">
|
||
Reliability of the <code>ephemeral</code> attribute
|
||
<a class="anchor" href="#reliability-of-the-ephemeral-attribute">#</a>
|
||
</h2>
|
||
<p>The Waku message <code>ephemeral</code> attribute is set by the sender.
|
||
Since there is currently no incentive mechanism for network participants to behave correctly, this attribute is inherently insecure.
|
||
A malicious actor can tamper with the value of a Waku message’s <code>ephemeral</code> attribute, and the receiver would not be able to verify the integrity of the message.</p>
|
||
<h2 id="copyright">
|
||
Copyright
|
||
<a class="anchor" href="#copyright">#</a>
|
||
</h2>
|
||
<p>Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p>
|
||
<h1 id="references">
|
||
References
|
||
<a class="anchor" href="#references">#</a>
|
||
</h1>
|
||
<ul>
|
||
<li><a href="/spec/6/">6/WAKU1</a></li>
|
||
<li><a href="https://developers.google.com/protocol-buffers/">Google Protocol buffers v3</a></li>
|
||
<li><a href="/spec/26">26/WAKU-PAYLOAD</a></li>
|
||
<li><a href="/spec/35">35/WAKU2-NOISE</a></li>
|
||
<li><a href="https://specs.status.im/spec/6#clock-vs-timestamp-and-message-ordering">6/PAYLOADS</a></li>
|
||
</ul>
|
||
</article>
|
||
|
||
|
||
|
||
<footer class="book-footer">
|
||
|
||
<div class="flex flex-wrap justify-between">
|
||
|
||
|
||
|
||
|
||
|
||
</div>
|
||
|
||
|
||
|
||
</footer>
|
||
|
||
|
||
|
||
<div class="book-comments">
|
||
|
||
</div>
|
||
|
||
|
||
|
||
<label for="menu-control" class="hidden book-menu-overlay"></label>
|
||
</div>
|
||
|
||
|
||
<aside class="book-toc">
|
||
<div class="book-toc-content">
|
||
|
||
|
||
<nav id="TableOfContents">
|
||
<ul>
|
||
<li><a href="#waku-message">Waku Message</a></li>
|
||
<li><a href="#message-attributes">Message Attributes</a></li>
|
||
</ul>
|
||
|
||
<ul>
|
||
<li><a href="#confidentiality-integrity-and-authenticity">Confidentiality, integrity, and authenticity</a></li>
|
||
<li><a href="#reliability-of-the-timestamp-attribute">Reliability of the <code>timestamp</code> attribute</a></li>
|
||
<li><a href="#reliability-of-the-ephemeral-attribute">Reliability of the <code>ephemeral</code> attribute</a></li>
|
||
<li><a href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
</nav>
|
||
|
||
|
||
|
||
</div>
|
||
</aside>
|
||
|
||
</main>
|
||
|
||
|
||
</body>
|
||
|
||
</html>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|