mirror of
https://github.com/acid-info/docs.wakuconnect.dev.git
synced 2025-02-22 14:48:06 +00:00
964 lines
34 KiB
HTML
964 lines
34 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en" dir="ltr">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta name="description" content="Encrypt Messages Using Waku Message Version 1 # The Waku Message format provides an easy way to encrypt messages using symmetric or asymmetric encryption. The encryption comes with several handy design requirements: confidentiality, authenticity and integrity. It also allows the sender to sign messages, see Sign Messages Using Waku Message Version 1 to learn how.
|
|
You can find more details about Waku Message Payload Encryption in 26/WAKU-PAYLOAD.
|
|
See Cryptographic Libraries for more details on the cryptographic libraries used by js-waku.">
|
|
<meta name="theme-color" content="#FFFFFF">
|
|
<meta name="color-scheme" content="light dark"><meta property="og:title" content="Encrypt Messages Using Waku Message Version 1" />
|
|
<meta property="og:description" content="Encrypt Messages Using Waku Message Version 1 # The Waku Message format provides an easy way to encrypt messages using symmetric or asymmetric encryption. The encryption comes with several handy design requirements: confidentiality, authenticity and integrity. It also allows the sender to sign messages, see Sign Messages Using Waku Message Version 1 to learn how.
|
|
You can find more details about Waku Message Payload Encryption in 26/WAKU-PAYLOAD.
|
|
See Cryptographic Libraries for more details on the cryptographic libraries used by js-waku." />
|
|
<meta property="og:type" content="article" />
|
|
<meta property="og:url" content="https://docs.wakuconnect.dev/docs/guides/04_encrypt_messages_version_1/" /><meta property="article:section" content="docs" />
|
|
<meta property="article:published_time" content="2021-12-09T14:00:00+01:00" />
|
|
<meta property="article:modified_time" content="2022-02-02T11:56:14+11:00" />
|
|
|
|
<title>Encrypt Messages Using Waku Message Version 1 | Waku Connect Docs</title>
|
|
<link rel="manifest" href="/manifest.json">
|
|
<link rel="icon" href="/favicon.png" type="image/x-icon">
|
|
<link rel="stylesheet" href="/book.min.89a77f7e702a8626749b948bbfb01109823daf6c1246ca407d1378833494c402.css" integrity="sha256-iad/fnAqhiZ0m5SLv7ARCYI9r2wSRspAfRN4gzSUxAI=" crossorigin="anonymous">
|
|
<script defer src="/flexsearch.min.js"></script>
|
|
<script defer src="/en.search.min.0d177fc31f8c8c2725b8432ee3b9a0c2b844f8660d18295053409cfed9db3843.js" integrity="sha256-DRd/wx+MjCcluEMu47mgwrhE+GYNGClQU0Cc/tnbOEM=" crossorigin="anonymous"></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 class="flex align-center" href="/"><span>Waku Connect Docs</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 class="book-languages">
|
|
<li>
|
|
<input type="checkbox" id="languages" class="toggle" />
|
|
<label for="languages" class="flex justify-between">
|
|
<a role="button" class="flex align-center">
|
|
<img src="/svg/translate.svg" class="book-icon" alt="Languages" />
|
|
English
|
|
</a>
|
|
</label>
|
|
|
|
<ul>
|
|
|
|
<li>
|
|
<a href="https://docs.wakuconnect.dev/es/">
|
|
Español
|
|
</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="https://docs.wakuconnect.dev/pt/">
|
|
Português
|
|
</a>
|
|
</li>
|
|
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/introduction/" class="">Introduction</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/quick_start/" class="">Quick Start</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/use_cases/" class="">Use Cases</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/presentations/" class="">Presentations & Videos</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/" class="">Guides</a>
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/01_choose_content_topic/" class="">How to Choose a Content Topic</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/02_relay_receive_send_messages/" class="">Receive and Send Messages Using Waku Relay</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/03_store_retrieve_messages/" class="">Retrieve Messages Using Waku Store</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/04_encrypt_messages_version_1/" class=" active">Encrypt Messages Using Waku Message Version 1</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/05_sign_messages_version_1/" class="">Sign Messages Using Waku Message Version 1</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/06_light_push_send_messages/" class="">Send Messages Using Waku Light Push</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/10_angular_relay/" class="">Send and Receive Messages Using Waku Relay With Angular v13</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/07_reactjs_relay/" class="">Receive and Send Messages Using Waku Relay With ReactJS</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/08_reactjs_store/" class="">Retrieve Messages Using Waku Store With ReactJS</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/09_debug/" class="">How to Debug your Waku dApp</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/11_nwaku/" class="">Nwaku Service Node</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/vote_poll_sdk/" class="">Vote Poll Sdk</a>
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/vote_poll_sdk/dapp_creation/" class="">Create a DApp</a>
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/vote_poll_sdk/dapp_creation/01_create_dapp/" class="">Create the DApp and Install Dependencies</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/vote_poll_sdk/dapp_creation/02_connect_wallet/" class="">Connect to the Ethereum Wallet</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/vote_poll_sdk/dapp_creation/03_connect_walle_usedapp/" class="">Connect to the Ethereum Wallet useDapp</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/vote_poll_sdk/poll_sdk/" class="">Poll SDK</a>
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/vote_poll_sdk/poll_sdk/01_create-a-poll_button/" class="">Create-A-Poll Button</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/vote_poll_sdk/poll_sdk/02_poll_creation/" class="">Poll Creation Component</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/vote_poll_sdk/poll_sdk/03_poll_list/" class="">Poll List Component</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/vote_poll_sdk/vote_sdk/" class="">Vote SDK</a>
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/vote_poll_sdk/vote_sdk/01_deploying_smart_contract/" class="">Deploy smart contract</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/vote_poll_sdk/vote_sdk/02_voting_creation/" class="">Creating Voting component</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/guides/vote_poll_sdk/vote_sdk/03_using_voting/" class="">Use Voting Component</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/examples/" class="">Examples</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/crypto_libraries/" class="">Cryptographic Libraries</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://docs.wakuconnect.dev/docs/waku_protocols/" class="">Implemented Waku Protocols</a>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
<li>
|
|
<a href="https://js-waku.wakuconnect.dev/" target="_blank" rel="noopener">
|
|
JS-Waku API Doc
|
|
</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="https://vac.dev/" target="_blank" rel="noopener">
|
|
Vac Team
|
|
</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="https://rfc.vac.dev/" target="_blank" rel="noopener">
|
|
Vac RFCs
|
|
</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="https://status.im/" target="_blank" rel="noopener">
|
|
Status.im
|
|
</a>
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</nav>
|
|
|
|
|
|
|
|
|
|
<script>(function(){var a=document.querySelector("aside .book-menu-content");addEventListener("beforeunload",function(b){localStorage.setItem("menu.scrollTop",a.scrollTop)}),a.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>Encrypt Messages Using Waku Message Version 1</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="#encrypt-messages-using-waku-message-version-1">Encrypt Messages Using Waku Message Version 1</a>
|
|
<ul>
|
|
<li><a href="#what-data-is-encrypted">What data is encrypted</a></li>
|
|
<li><a href="#key-management">Key management</a></li>
|
|
<li><a href="#which-encryption-method-should-i-use">Which encryption method should I use?</a></li>
|
|
<li><a href="#symmetric-encryption">Symmetric Encryption</a>
|
|
<ul>
|
|
<li><a href="#generate-key">Generate Key</a></li>
|
|
<li><a href="#encrypt-message">Encrypt Message</a></li>
|
|
<li><a href="#decrypt-messages">Decrypt Messages</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#asymmetric-encryption">Asymmetric Encryption</a>
|
|
<ul>
|
|
<li><a href="#generate-key-pair">Generate Key Pair</a></li>
|
|
<li><a href="#encrypt-message-1">Encrypt Message</a></li>
|
|
<li><a href="#decrypt-messages-1">Decrypt Messages</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#handling-wakumessage-instances">Handling <code>WakuMessage</code> instances</a></li>
|
|
<li><a href="#code-example">Code Example</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</nav>
|
|
|
|
|
|
|
|
</aside>
|
|
|
|
|
|
</header>
|
|
|
|
|
|
|
|
<article class="markdown"><h1 id="encrypt-messages-using-waku-message-version-1">
|
|
Encrypt Messages Using Waku Message Version 1
|
|
<a class="anchor" href="#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.
|
|
It also allows the sender to sign messages,
|
|
see <a href="/docs/guides/05_sign_messages_version_1/">Sign Messages Using Waku Message Version 1</a> to learn how.</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>
|
|
<p>See <a href="/docs/crypto_libraries/">Cryptographic Libraries</a> for more details on the cryptographic libraries used by js-waku.</p>
|
|
<h2 id="what-data-is-encrypted">
|
|
What data is encrypted
|
|
<a class="anchor" href="#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">
|
|
Key management
|
|
<a class="anchor" href="#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">
|
|
Which encryption method should I use?
|
|
<a class="anchor" href="#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">
|
|
Symmetric Encryption
|
|
<a class="anchor" href="#symmetric-encryption">#</a>
|
|
</h2>
|
|
<h3 id="generate-key">
|
|
Generate Key
|
|
<a class="anchor" href="#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>
|
|
<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-js" data-lang="js"><span style="color:#66d9ef">import</span> { <span style="color:#a6e22e">generateSymmetricKey</span> } <span style="color:#a6e22e">from</span> <span style="color:#e6db74">"js-waku"</span>;
|
|
|
|
<span style="color:#66d9ef">const</span> <span style="color:#a6e22e">symmetricKey</span> <span style="color:#f92672">=</span> <span style="color:#a6e22e">generateSymmetricKey</span>();
|
|
</code></pre></div><h3 id="encrypt-message">
|
|
Encrypt Message
|
|
<a class="anchor" href="#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="/docs/guides/02_relay_receive_send_messages/">Receive and Send Messages Using Waku Relay</a> for details.</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-js" data-lang="js"><span style="color:#66d9ef">import</span> { <span style="color:#a6e22e">WakuMessage</span> } <span style="color:#a6e22e">from</span> <span style="color:#e6db74">"js-waku"</span>;
|
|
|
|
<span style="color:#66d9ef">const</span> <span style="color:#a6e22e">message</span> <span style="color:#f92672">=</span> <span style="color:#66d9ef">await</span> <span style="color:#a6e22e">WakuMessage</span>.<span style="color:#a6e22e">fromBytes</span>(<span style="color:#a6e22e">payload</span>, <span style="color:#a6e22e">contentTopic</span>, {
|
|
<span style="color:#a6e22e">symKey</span><span style="color:#f92672">:</span> <span style="color:#a6e22e">symmetricKey</span>,
|
|
});
|
|
</code></pre></div><p>The Waku Message can then be sent to the Waku network using Waku Relay or Waku Light Push:</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-js" data-lang="js"><span style="color:#66d9ef">await</span> <span style="color:#a6e22e">waku</span>.<span style="color:#a6e22e">lightPush</span>.<span style="color:#a6e22e">push</span>(<span style="color:#a6e22e">message</span>);
|
|
</code></pre></div><h3 id="decrypt-messages">
|
|
Decrypt Messages
|
|
<a class="anchor" href="#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>
|
|
<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-js" data-lang="js"><span style="color:#a6e22e">waku</span>.<span style="color:#a6e22e">addDecryptionKey</span>(<span style="color:#a6e22e">symmetricKey</span>);
|
|
</code></pre></div><p>Alternatively, you can pass the key when creating the instance:</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-js" data-lang="js"><span style="color:#66d9ef">import</span> { <span style="color:#a6e22e">Waku</span> } <span style="color:#a6e22e">from</span> <span style="color:#e6db74">"js-waku"</span>;
|
|
|
|
<span style="color:#66d9ef">const</span> <span style="color:#a6e22e">waku</span> <span style="color:#f92672">=</span> <span style="color:#a6e22e">Waku</span>.<span style="color:#a6e22e">create</span>({ <span style="color:#a6e22e">decryptionKeys</span><span style="color:#f92672">:</span> [<span style="color:#a6e22e">symmetricKey</span>] });
|
|
</code></pre></div><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">
|
|
Asymmetric Encryption
|
|
<a class="anchor" href="#asymmetric-encryption">#</a>
|
|
</h2>
|
|
<h3 id="generate-key-pair">
|
|
Generate Key Pair
|
|
<a class="anchor" href="#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>
|
|
<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-js" data-lang="js"><span style="color:#66d9ef">import</span> { <span style="color:#a6e22e">generatePrivateKey</span>, <span style="color:#a6e22e">getPublicKey</span> } <span style="color:#a6e22e">from</span> <span style="color:#e6db74">"js-waku"</span>;
|
|
|
|
<span style="color:#66d9ef">const</span> <span style="color:#a6e22e">privateKey</span> <span style="color:#f92672">=</span> <span style="color:#a6e22e">generatePrivateKey</span>();
|
|
<span style="color:#66d9ef">const</span> <span style="color:#a6e22e">publicKey</span> <span style="color:#f92672">=</span> <span style="color:#a6e22e">getPublicKey</span>(<span style="color:#a6e22e">privateKey</span>);
|
|
</code></pre></div><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">
|
|
Encrypt Message
|
|
<a class="anchor" href="#encrypt-message-1">#</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="/docs/guides/02_relay_receive_send_messages/">Receive and Send Messages Using Waku Relay</a> for details.</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-js" data-lang="js"><span style="color:#66d9ef">import</span> { <span style="color:#a6e22e">WakuMessage</span> } <span style="color:#a6e22e">from</span> <span style="color:#e6db74">"js-waku"</span>;
|
|
|
|
<span style="color:#66d9ef">const</span> <span style="color:#a6e22e">message</span> <span style="color:#f92672">=</span> <span style="color:#66d9ef">await</span> <span style="color:#a6e22e">WakuMessage</span>.<span style="color:#a6e22e">fromBytes</span>(<span style="color:#a6e22e">payload</span>, <span style="color:#a6e22e">contentTopic</span>, {
|
|
<span style="color:#a6e22e">encPublicKey</span><span style="color:#f92672">:</span> <span style="color:#a6e22e">publicKey</span>,
|
|
});
|
|
</code></pre></div><p>The Waku Message can then be sent to the Waku network using Waku Relay or Waku Light Push:</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-js" data-lang="js"><span style="color:#66d9ef">await</span> <span style="color:#a6e22e">waku</span>.<span style="color:#a6e22e">lightPush</span>.<span style="color:#a6e22e">push</span>(<span style="color:#a6e22e">message</span>);
|
|
</code></pre></div><h3 id="decrypt-messages-1">
|
|
Decrypt Messages
|
|
<a class="anchor" href="#decrypt-messages-1">#</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>
|
|
<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-js" data-lang="js"><span style="color:#a6e22e">waku</span>.<span style="color:#a6e22e">addDecryptionKey</span>(<span style="color:#a6e22e">privateKey</span>);
|
|
</code></pre></div><p>Alternatively, you can pass the key when creating the instance:</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-js" data-lang="js"><span style="color:#66d9ef">import</span> { <span style="color:#a6e22e">Waku</span> } <span style="color:#a6e22e">from</span> <span style="color:#e6db74">"js-waku"</span>;
|
|
|
|
<span style="color:#66d9ef">const</span> <span style="color:#a6e22e">waku</span> <span style="color:#f92672">=</span> <span style="color:#a6e22e">Waku</span>.<span style="color:#a6e22e">create</span>({ <span style="color:#a6e22e">decryptionKeys</span><span style="color:#f92672">:</span> [<span style="color:#a6e22e">privateKey</span>] });
|
|
</code></pre></div><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">
|
|
Handling <code>WakuMessage</code> instances
|
|
<a class="anchor" href="#handling-wakumessage-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>
|
|
<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-js" data-lang="js"><span style="color:#66d9ef">import</span> { <span style="color:#a6e22e">WakuMessage</span> } <span style="color:#a6e22e">from</span> <span style="color:#e6db74">"js-waku"</span>;
|
|
|
|
<span style="color:#66d9ef">const</span> <span style="color:#a6e22e">message</span> <span style="color:#f92672">=</span> <span style="color:#66d9ef">await</span> <span style="color:#a6e22e">WakuMessage</span>.<span style="color:#a6e22e">fromBytes</span>(<span style="color:#a6e22e">payload</span>, <span style="color:#a6e22e">contentTopic</span>, {
|
|
<span style="color:#a6e22e">encPublicKey</span><span style="color:#f92672">:</span> <span style="color:#a6e22e">publicKey</span>,
|
|
});
|
|
|
|
<span style="color:#a6e22e">console</span>.<span style="color:#a6e22e">log</span>(<span style="color:#a6e22e">message</span>.<span style="color:#a6e22e">payload</span>); <span style="color:#75715e">// This is encrypted
|
|
</span></code></pre></div><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>
|
|
<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-js" data-lang="js"><span style="color:#66d9ef">import</span> { <span style="color:#a6e22e">Waku</span> } <span style="color:#a6e22e">from</span> <span style="color:#e6db74">"js-waku"</span>;
|
|
|
|
<span style="color:#66d9ef">const</span> <span style="color:#a6e22e">waku</span> <span style="color:#f92672">=</span> <span style="color:#a6e22e">Waku</span>.<span style="color:#a6e22e">create</span>({ <span style="color:#a6e22e">decryptionKeys</span><span style="color:#f92672">:</span> [<span style="color:#a6e22e">privateKey</span>] });
|
|
|
|
<span style="color:#66d9ef">const</span> <span style="color:#a6e22e">messages</span> <span style="color:#f92672">=</span> <span style="color:#66d9ef">await</span> <span style="color:#a6e22e">waku</span>.<span style="color:#a6e22e">store</span>.<span style="color:#a6e22e">queryHistory</span>([<span style="color:#a6e22e">contentTopic</span>]);
|
|
|
|
<span style="color:#66d9ef">if</span> (<span style="color:#a6e22e">messages</span> <span style="color:#f92672">&&</span> <span style="color:#a6e22e">messages</span>[<span style="color:#ae81ff">0</span>]) {
|
|
<span style="color:#a6e22e">console</span>.<span style="color:#a6e22e">log</span>(<span style="color:#a6e22e">messages</span>[<span style="color:#ae81ff">0</span>].<span style="color:#a6e22e">payload</span>); <span style="color:#75715e">// This payload is decrypted
|
|
</span><span style="color:#75715e"></span>}
|
|
|
|
<span style="color:#a6e22e">waku</span>.<span style="color:#a6e22e">relay</span>.<span style="color:#a6e22e">addObserver</span>(
|
|
(<span style="color:#a6e22e">message</span>) => {
|
|
<span style="color:#a6e22e">console</span>.<span style="color:#a6e22e">log</span>(<span style="color:#a6e22e">message</span>.<span style="color:#a6e22e">payload</span>); <span style="color:#75715e">// This payload is decrypted
|
|
</span><span style="color:#75715e"></span> },
|
|
[<span style="color:#a6e22e">contentTopic</span>]
|
|
);
|
|
</code></pre></div><h2 id="code-example">
|
|
Code Example
|
|
<a class="anchor" href="#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 <a href="https://js-waku.wakuconnect.dev/examples/eth-pm">https://js-waku.wakuconnect.dev/examples/eth-pm</a>.</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>
|
|
</article>
|
|
|
|
|
|
|
|
<footer class="book-footer">
|
|
|
|
<div class="flex flex-wrap justify-between">
|
|
|
|
|
|
<div><a class="flex align-center" href="https://github.com/vacp2p/docs.wakuconnect.dev/commit/9f9d3eb6b803b31e514a75d7b047eeb81268e76b" title='Last modified by Franck R | Feb 2, 2022' target="_blank" rel="noopener">
|
|
<img src="/svg/calendar.svg" class="book-icon" alt="Calendar" />
|
|
<span>Feb 2, 2022</span>
|
|
</a>
|
|
</div>
|
|
|
|
|
|
|
|
<div>
|
|
<a class="flex align-center" href="https://github.com/vacp2p/docs.wakuconnect.dev/edit/develop/content/docs/guides/04_encrypt_messages_version_1.md" target="_blank" rel="noopener">
|
|
<img src="/svg/edit.svg" class="book-icon" alt="Edit" />
|
|
<span>Edit this page</span>
|
|
</a>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
<script>(function(){function a(c){const a=window.getSelection(),b=document.createRange();b.selectNodeContents(c),a.removeAllRanges(),a.addRange(b)}document.querySelectorAll("pre code").forEach(b=>{b.addEventListener("click",function(c){a(b.parentElement),navigator.clipboard&&navigator.clipboard.writeText(b.parentElement.textContent)})})})()</script>
|
|
|
|
|
|
|
|
|
|
</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="#encrypt-messages-using-waku-message-version-1">Encrypt Messages Using Waku Message Version 1</a>
|
|
<ul>
|
|
<li><a href="#what-data-is-encrypted">What data is encrypted</a></li>
|
|
<li><a href="#key-management">Key management</a></li>
|
|
<li><a href="#which-encryption-method-should-i-use">Which encryption method should I use?</a></li>
|
|
<li><a href="#symmetric-encryption">Symmetric Encryption</a>
|
|
<ul>
|
|
<li><a href="#generate-key">Generate Key</a></li>
|
|
<li><a href="#encrypt-message">Encrypt Message</a></li>
|
|
<li><a href="#decrypt-messages">Decrypt Messages</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#asymmetric-encryption">Asymmetric Encryption</a>
|
|
<ul>
|
|
<li><a href="#generate-key-pair">Generate Key Pair</a></li>
|
|
<li><a href="#encrypt-message-1">Encrypt Message</a></li>
|
|
<li><a href="#decrypt-messages-1">Decrypt Messages</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#handling-wakumessage-instances">Handling <code>WakuMessage</code> instances</a></li>
|
|
<li><a href="#code-example">Code Example</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</nav>
|
|
|
|
|
|
|
|
</div>
|
|
</aside>
|
|
|
|
</main>
|
|
|
|
|
|
</body>
|
|
</html>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|