mirror of
https://github.com/acid-info/docs.wakuconnect.dev.git
synced 2025-02-23 06:58:19 +00:00
359 lines
23 KiB
HTML
359 lines
23 KiB
HTML
<!DOCTYPE HTML>
|
|
<html lang="en" class="sidebar-visible no-js light">
|
|
<head>
|
|
<!-- Book generated using mdBook -->
|
|
<meta charset="UTF-8">
|
|
<title>Encrypt Messages Using Waku Message Version 1 - DappConnect Docs</title>
|
|
|
|
|
|
<!-- Custom HTML head -->
|
|
|
|
|
|
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
|
|
<meta name="description" content="">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<meta name="theme-color" content="#ffffff" />
|
|
|
|
<link rel="icon" href="../favicon.svg">
|
|
<link rel="shortcut icon" href="../favicon.png">
|
|
<link rel="stylesheet" href="../css/variables.css">
|
|
<link rel="stylesheet" href="../css/general.css">
|
|
<link rel="stylesheet" href="../css/chrome.css">
|
|
<link rel="stylesheet" href="../css/print.css" media="print">
|
|
|
|
<!-- Fonts -->
|
|
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
|
|
<link rel="stylesheet" href="../fonts/fonts.css">
|
|
|
|
<!-- Highlight.js Stylesheets -->
|
|
<link rel="stylesheet" href="../highlight.css">
|
|
<link rel="stylesheet" href="../tomorrow-night.css">
|
|
<link rel="stylesheet" href="../ayu-highlight.css">
|
|
|
|
<!-- Custom theme stylesheets -->
|
|
<link rel="stylesheet" href="../custom.css">
|
|
|
|
</head>
|
|
<body>
|
|
<!-- Provide site root to javascript -->
|
|
<script type="text/javascript">
|
|
var path_to_root = "../";
|
|
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
|
|
</script>
|
|
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
|
<script type="text/javascript">
|
|
try {
|
|
var theme = localStorage.getItem('mdbook-theme');
|
|
var sidebar = localStorage.getItem('mdbook-sidebar');
|
|
|
|
if (theme.startsWith('"') && theme.endsWith('"')) {
|
|
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
|
}
|
|
|
|
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
|
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
|
}
|
|
} catch (e) { }
|
|
</script>
|
|
|
|
<!-- Set the theme before any content is loaded, prevents flash -->
|
|
<script type="text/javascript">
|
|
var theme;
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
|
var html = document.querySelector('html');
|
|
html.classList.remove('no-js')
|
|
html.classList.remove('light')
|
|
html.classList.add(theme);
|
|
html.classList.add('js');
|
|
</script>
|
|
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
|
<script type="text/javascript">
|
|
var html = document.querySelector('html');
|
|
var sidebar = 'hidden';
|
|
if (document.body.clientWidth >= 1080) {
|
|
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
|
sidebar = sidebar || 'visible';
|
|
}
|
|
html.classList.remove('sidebar-visible');
|
|
html.classList.add("sidebar-" + sidebar);
|
|
</script>
|
|
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
|
<div class="sidebar-scrollbox">
|
|
<ol class="chapter"><li class="chapter-item expanded affix "><a href="../introduction.html">Introduction</a></li><li class="chapter-item expanded "><a href="../quick_start.html"><strong aria-hidden="true">1.</strong> Quick Start</a></li><li class="chapter-item expanded "><a href="../guides/index.html"><strong aria-hidden="true">2.</strong> Guides</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="../guides/choose_content_topic.html"><strong aria-hidden="true">2.1.</strong> How to Choose a Content Topic</a></li><li class="chapter-item expanded "><a href="../guides/relay_receive_send_messages.html"><strong aria-hidden="true">2.2.</strong> Receive and Send Messages Using Waku Relay</a></li><li class="chapter-item expanded "><a href="../guides/store_retrieve_messages.html"><strong aria-hidden="true">2.3.</strong> Retrieve Messages Using Waku Store</a></li><li class="chapter-item expanded "><a href="../guides/encrypt_messages_version_1.html" class="active"><strong aria-hidden="true">2.4.</strong> Encrypt Messages Using Waku Message Version 1</a></li><li class="chapter-item expanded "><a href="../guides/reactjs_relay.html"><strong aria-hidden="true">2.5.</strong> Receive and Send Messages Using Waku Relay With ReactJS</a></li><li class="chapter-item expanded "><a href="../guides/reactjs_store.html"><strong aria-hidden="true">2.6.</strong> Retrieve Messages Using Waku Store With ReactJS</a></li><li class="chapter-item expanded "><a href="../guides/light_push_send_messages.html"><strong aria-hidden="true">2.7.</strong> Send Messages Using Waku Light Push</a></li></ol></li><li class="chapter-item expanded "><a href="../examples.html"><strong aria-hidden="true">3.</strong> Examples</a></li><li class="chapter-item expanded affix "><a href="../waku_protocols.html">Implemented Waku Protocols</a></li></ol> </div>
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
|
|
</nav>
|
|
|
|
<div id="page-wrapper" class="page-wrapper">
|
|
|
|
<div class="page">
|
|
|
|
<div id="menu-bar-hover-placeholder"></div>
|
|
<div id="menu-bar" class="menu-bar sticky bordered">
|
|
<div class="left-buttons">
|
|
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
|
<i class="fa fa-bars"></i>
|
|
</button>
|
|
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
|
<i class="fa fa-paint-brush"></i>
|
|
</button>
|
|
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
|
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
|
</ul>
|
|
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
|
<i class="fa fa-search"></i>
|
|
</button>
|
|
</div>
|
|
|
|
<h1 class="menu-title">DappConnect Docs</h1>
|
|
|
|
<div class="right-buttons">
|
|
<a href="../print.html" title="Print this book" aria-label="Print this book">
|
|
<i id="print-button" class="fa fa-print"></i>
|
|
</a>
|
|
<a href="https://github.com/vacp2p/docs.dappconnect.dev" title="Git repository" aria-label="Git repository">
|
|
<i id="git-repository-button" class="fa fa-github"></i>
|
|
</a>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div id="search-wrapper" class="hidden">
|
|
<form id="searchbar-outer" class="searchbar-outer">
|
|
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
|
</form>
|
|
<div id="searchresults-outer" class="searchresults-outer hidden">
|
|
<div id="searchresults-header" class="searchresults-header"></div>
|
|
<ul id="searchresults">
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
|
<script type="text/javascript">
|
|
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
|
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
|
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
|
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
|
});
|
|
</script>
|
|
|
|
<div id="content" class="content">
|
|
<main>
|
|
<h1 id="encrypt-messages-using-waku-message-version-1"><a class="header" href="#encrypt-messages-using-waku-message-version-1">Encrypt Messages Using Waku Message Version 1</a></h1>
|
|
<p>The Waku Message format provides an easy way to encrypt messages using symmetric or asymmetric encryption.
|
|
The encryption comes with several handy <a href="https://rfc.vac.dev/spec/26/#design-requirements">design requirements</a>:
|
|
confidentiality, authenticity and integrity.</p>
|
|
<p>You can find more details about Waku Message Payload Encryption in <a href="https://rfc.vac.dev/spec/26/">26/WAKU-PAYLOAD</a>.</p>
|
|
<h2 id="what-data-is-encrypted"><a class="header" href="#what-data-is-encrypted">What data is encrypted</a></h2>
|
|
<p>With Waku Message Version 1, the entire payload is encrypted.</p>
|
|
<p>Which means that the only discriminating data available in clear text is the content topic and timestamp (if present).
|
|
Hence, if Alice expects to receive messages under a given content topic, she needs to try to decrypt all messages received on said content topic.</p>
|
|
<p>This needs to be kept in mind for scalability and forward secrecy concerns:</p>
|
|
<ul>
|
|
<li>If there is high traffic on a given content topic then all clients need to process and attempt decryption of all messages with said content topic;</li>
|
|
<li>If a content topic is only used by a given (group of) user(s) then it is possible to deduce some information about said user(s) communications such as sent time and frequency of messages.</li>
|
|
</ul>
|
|
<h2 id="key-management"><a class="header" href="#key-management">Key management</a></h2>
|
|
<p>By using Waku Message Version 1, you will need to provide a way to your users to generate and store keys in a secure manner.
|
|
Storing, backing up and recovering key is out of the scope of this guide.</p>
|
|
<p>If key recovery is important for your dApp, then check out
|
|
<a href="https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/wrapKey">SubtleCrypto.wrapKey()</a> which can be used to securely store or export private keys.</p>
|
|
<p>An example to save and load a key pair in local storage, protected with a password, can be found in <a href="https://github.com/status-im/js-waku/blob/main/examples/eth-pm/src/key_pair_handling/key_pair_storage.ts">Eth-PM</a>.</p>
|
|
<h2 id="which-encryption-method-should-i-use"><a class="header" href="#which-encryption-method-should-i-use">Which encryption method should I use?</a></h2>
|
|
<p>Whether you should use symmetric or asymmetric encryption depends on your use case.</p>
|
|
<p><strong>Symmetric</strong> encryption is done using a single key to encrypt and decrypt.</p>
|
|
<p>Which means that if Alice knows the symmetric key <code>K</code> and uses it to encrypt a message,
|
|
she can also use <code>K</code> to decrypt any message encrypted with <code>K</code>,
|
|
even if she is not the sender.</p>
|
|
<p>Group chats is a possible use case for symmetric encryption:
|
|
All participants can use an out-of-band method to agree on a <code>K</code>.
|
|
Participants can then use <code>K</code> to encrypt and decrypt messages within the group chat.
|
|
Participants MUST keep <code>K</code> secret to ensure that no external party can decrypt the group chat messages.</p>
|
|
<p><strong>Asymmetric</strong> encryption is done using a key pair:
|
|
the public key is used to encrypt messages,
|
|
the matching private key is used to decrypt messages.</p>
|
|
<p>For Alice to encrypt a message for Bob, she needs to know Bob's Public Key <code>K</code>.
|
|
Bob can then use his private key <code>k</code> to decrypt the message.
|
|
As long as Bob keep his private key <code>k</code> secret, then he, and only he, can decrypt messages encrypted with <code>K</code>.</p>
|
|
<p>Private 1:1 messaging is a possible use case for asymmetric encryption:
|
|
When Alice sends an encrypted message for Bob, only Bob can decrypt it.</p>
|
|
<h2 id="symmetric-encryption"><a class="header" href="#symmetric-encryption">Symmetric Encryption</a></h2>
|
|
<h3 id="generate-key"><a class="header" href="#generate-key">Generate Key</a></h3>
|
|
<p>To use symmetric encryption, you first need to generate a key.
|
|
Use <code>generateSymmetricKey</code> for secure key generation:</p>
|
|
<pre><code class="language-js">import { generateSymmetricKey } from 'js-waku';
|
|
|
|
const symmetricKey = generateSymmetricKey();
|
|
</code></pre>
|
|
<h3 id="encrypt-message"><a class="header" href="#encrypt-message">Encrypt Message</a></h3>
|
|
<p>To encrypt a message with the previously generated key,
|
|
pass the key in the <code>symKey</code> property to <code>WakuMessage.fromBytes</code>.</p>
|
|
<p>Same as Waku Messages version 0 (unencrypted),
|
|
<code>payload</code> is your message payload and <code>contentTopic</code> is the content topic for your dApp.
|
|
See <a href="./relay_receive_send_messages.html">Receive and Send Messages Using Waku Relay</a> for details.</p>
|
|
<pre><code class="language-js">import { WakuMessage } from 'js-waku';
|
|
|
|
const message = await WakuMessage.fromBytes(payload, contentTopic, {
|
|
symKey: symmetricKey
|
|
});
|
|
</code></pre>
|
|
<p>The Waku Message can then be sent to the Waku network using Waku Relay or Waku Light Push:</p>
|
|
<pre><code class="language-js">await waku.lightPush.push(message);
|
|
</code></pre>
|
|
<h3 id="decrypt-messages"><a class="header" href="#decrypt-messages">Decrypt Messages</a></h3>
|
|
<p>To decrypt messages,
|
|
whether they are received over Waku Relay or using Waku Store,
|
|
add the symmetric key as a decryption key to your Waku instance.</p>
|
|
<pre><code class="language-js">waku.addDecryptionKey(symmetricKey);
|
|
</code></pre>
|
|
<p>Alternatively, you can pass the key when creating the instance:</p>
|
|
<pre><code class="language-js">import { Waku } from 'js-waku';
|
|
|
|
const waku = Waku.create({ decryptionKeys: [symmetricKey] });
|
|
</code></pre>
|
|
<p>It will attempt to decrypt any message it receives using the key, for both symmetric and asymmetric encryption.</p>
|
|
<p>You can call <code>addDecryptionKey</code> several times if you are using multiple keys,
|
|
symmetric key and asymmetric private keys can be used together.</p>
|
|
<p>Messages that are not successfully decrypted are dropped.</p>
|
|
<h2 id="asymmetric-encryption"><a class="header" href="#asymmetric-encryption">Asymmetric Encryption</a></h2>
|
|
<h3 id="generate-key-pair"><a class="header" href="#generate-key-pair">Generate Key Pair</a></h3>
|
|
<p>To use asymmetric encryption, you first need to generate a private key and calculate the corresponding public key.
|
|
Use <code>generatePrivateKey</code> for secure key generation:</p>
|
|
<pre><code class="language-js">import { generatePrivateKey, getPublicKey } from 'js-waku';
|
|
|
|
const privateKey = generatePrivateKey();
|
|
const publicKey = getPublicKey(privateKey);
|
|
</code></pre>
|
|
<p>The private key must be securely stored and remain private.
|
|
If leaked then other parties may be able to decrypt the user's messages.</p>
|
|
<p>The public key is unique for a given private key and can always be recovered given the private key,
|
|
hence it is not needed to save it as long as as the private key can be recovered.</p>
|
|
<h3 id="encrypt-message-1"><a class="header" href="#encrypt-message-1">Encrypt Message</a></h3>
|
|
<p>The public key is used to encrypt messages;
|
|
to do so, pass it in the <code>encPublicKey</code> property to <code>WakuMessage.fromBytes</code>.</p>
|
|
<p>Same as clear Waku Messages,
|
|
<code>payload</code> is your message payload and <code>contentTopic</code> is the content topic for your dApp.
|
|
See <a href="./relay_receive_send_messages.html">Receive and Send Messages Using Waku Relay</a> for details.</p>
|
|
<pre><code class="language-js">import { WakuMessage } from 'js-waku';
|
|
|
|
const message = await WakuMessage.fromBytes(payload, contentTopic, {
|
|
encPublicKey: publicKey
|
|
});
|
|
</code></pre>
|
|
<p>The Waku Message can then be sent to the Waku network using Waku Relay or Waku Light Push:</p>
|
|
<pre><code class="language-js">await waku.lightPush.push(message);
|
|
</code></pre>
|
|
<h3 id="decrypt-messages-1"><a class="header" href="#decrypt-messages-1">Decrypt Messages</a></h3>
|
|
<p>The private key is needed to decrypt messages.</p>
|
|
<p>To decrypt messages,
|
|
whether they are received over Waku Relay or using Waku Store,
|
|
add the private key as a decryption key to your Waku instance.</p>
|
|
<pre><code class="language-js">waku.addDecryptionKey(privateKey);
|
|
</code></pre>
|
|
<p>Alternatively, you can pass the key when creating the instance:</p>
|
|
<pre><code class="language-js">import { Waku } from 'js-waku';
|
|
|
|
const waku = Waku.create({ decryptionKeys: [privateKey] });
|
|
</code></pre>
|
|
<p>It will attempt to decrypt any message it receives using the key, for both symmetric and asymmetric encryption.</p>
|
|
<p>You can call <code>addDecryptionKey</code> several times if you are using multiple keys,
|
|
symmetric key and asymmetric private keys can be used together.</p>
|
|
<p>Messages that are not successfully decrypted are dropped.</p>
|
|
<h2 id="handling-wakumessage-instances"><a class="header" href="#handling-wakumessage-instances">Handling <code>WakuMessage</code> instances</a></h2>
|
|
<p>When creating a Waku Message using <code>WakuMessage.fromBytes</code> with an encryption key (symmetric or asymmetric),
|
|
the payload gets encrypted.
|
|
Which means that <code>wakuMessage.payload</code> returns an encrypted payload:</p>
|
|
<pre><code class="language-js">import { WakuMessage } from 'js-waku';
|
|
|
|
const message = await WakuMessage.fromBytes(payload, contentTopic, {
|
|
encPublicKey: publicKey
|
|
});
|
|
|
|
console.log(message.payload); // This is encrypted
|
|
</code></pre>
|
|
<p>However, <code>WakuMessage</code> instances returned by <code>WakuRelay</code> or <code>WakuStore</code> are always decrypted.</p>
|
|
<p><code>WakuRelay</code> and <code>WakuStore</code> never return messages that are encrypted.
|
|
If a message was not successfully decrypted, then it will be dropped from the results.</p>
|
|
<p>Which means that <code>WakuMessage</code> instances returned by <code>WakuRelay</code> and <code>WakuStore</code> always have a clear payload (in regard to Waku Message version 1):</p>
|
|
<pre><code class="language-js">import { Waku } from 'js-waku';
|
|
|
|
const waku = Waku.create({ decryptionKeys: [privateKey] });
|
|
|
|
const messages = await waku.store.queryHistory([contentTopic]);
|
|
|
|
if (messages && messages[0]) {
|
|
console.log(messages[0].payload); // This payload is decrypted
|
|
}
|
|
|
|
waku.relay.addObserver((message) => {
|
|
console.log(message.payload); // This payload is decrypted
|
|
}, [contentTopic]);
|
|
</code></pre>
|
|
<h2 id="code-example"><a class="header" href="#code-example">Code Example</a></h2>
|
|
<p>The <a href="https://github.com/status-im/js-waku/tree/main/examples/eth-pm">Eth-PM</a> Web App example demonstrates both the use of symmetric and asymmetric encryption.</p>
|
|
<p>Asymmetric encryption is used for private messages so that only the intended recipient can read said messages.</p>
|
|
<p>Symmetric encryption is used for the public key messages.
|
|
In this instance, the same key is used for all users: the Keccak-256 hash of the content topic (which results in 32 bytes array).
|
|
While this does not add functional value, it does demonstrate the usage of symmetric encryption in a web app.</p>
|
|
<p>A live version of Eth-PM can be found at https://status-im.github.io/js-waku/eth-pm/.</p>
|
|
<p>The specifications of the protocol it implements can be found at <a href="https://rfc.vac.dev/spec/20/">20/TOY-ETH-PM</a>.</p>
|
|
|
|
</main>
|
|
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|
<!-- Mobile navigation buttons -->
|
|
<a rel="prev" href="../guides/store_retrieve_messages.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|
<i class="fa fa-angle-left"></i>
|
|
</a>
|
|
|
|
<a rel="next" href="../guides/reactjs_relay.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
|
|
<div style="clear: both"></div>
|
|
</nav>
|
|
</div>
|
|
</div>
|
|
|
|
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
|
<a rel="prev" href="../guides/store_retrieve_messages.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|
<i class="fa fa-angle-left"></i>
|
|
</a>
|
|
|
|
<a rel="next" href="../guides/reactjs_relay.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
</nav>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript">
|
|
window.playground_copyable = true;
|
|
</script>
|
|
|
|
|
|
<script src="../elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="../mark.min.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="../searcher.js" type="text/javascript" charset="utf-8"></script>
|
|
|
|
<script src="../clipboard.min.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="../highlight.js" type="text/javascript" charset="utf-8"></script>
|
|
<script src="../book.js" type="text/javascript" charset="utf-8"></script>
|
|
|
|
<!-- Custom JS scripts -->
|
|
|
|
|
|
</body>
|
|
</html>
|