diff --git a/docs/guides/js-waku/index.md b/docs/guides/js-waku/index.md index 066d6cc..606b337 100644 --- a/docs/guides/js-waku/index.md +++ b/docs/guides/js-waku/index.md @@ -85,7 +85,7 @@ Have a look at the quick start guide and comprehensive tutorials to learn how to | - | - | | [Send and Receive Messages Using Light Push and Filter](/guides/js-waku/light-send-receive) | Learn how to send and receive messages on light nodes using the [Light Push](/learn/concepts/protocols#light-push) and [Filter](/learn/concepts/protocols#filter) protocols | | [Retrieve Messages Using Store Protocol](/guides/js-waku/store-retrieve-messages) | Learn how to retrieve and filter historical messages on light nodes using the [Store protocol](/learn/concepts/protocols#store) | -| [Encrypt and Decrypt Your Waku Messages](/guides/js-waku/message-encryption) | Learn how to use the [@waku/message-encryption](https://www.npmjs.com/package/@waku/message-encryption) package to encrypt and decrypt your messages | +| [Encrypt, Decrypt, and Sign Your Messages](/guides/js-waku/message-encryption) | Learn how to use the [@waku/message-encryption](https://www.npmjs.com/package/@waku/message-encryption) package to encrypt, decrypt, and sign your messages | | [Build React DApps Using @waku/react](/guides/js-waku/use-waku-react) | Learn how to use the [@waku/react](https://www.npmjs.com/package/@waku/react) package seamlessly integrate `@waku/sdk` into a React application | | [Scaffold DApps Using @waku/create-app](/guides/js-waku/use-waku-create-app) | Learn how to use the [@waku/create-app](https://www.npmjs.com/package/@waku/create-app) package to bootstrap your next `@waku/sdk` project from various example templates | | [Bootstrap Nodes and Discover Peers](/guides/js-waku/configure-discovery) | Learn how to bootstrap your node using [Static Peers](/learn/concepts/static-peers) and discover peers using [DNS Discovery](/learn/concepts/dns-discovery) | diff --git a/docs/guides/js-waku/message-encryption.md b/docs/guides/js-waku/message-encryption.md index 9b1c21e..fa85995 100644 --- a/docs/guides/js-waku/message-encryption.md +++ b/docs/guides/js-waku/message-encryption.md @@ -1,9 +1,9 @@ --- -title: Encrypt and Decrypt Your Waku Messages +title: Encrypt, Decrypt, and Sign Your Messages hide_table_of_contents: true --- -This guide provides detailed steps to use the [@waku/message-encryption](https://www.npmjs.com/package/@waku/message-encryption) package to encrypt and decrypt your messages using [Waku message payload encryption](/learn/glossary#waku-message-payload-encryption) methods. +This guide provides detailed steps to use the [@waku/message-encryption](https://www.npmjs.com/package/@waku/message-encryption) package to encrypt, decrypt, and sign your messages using [Waku message payload encryption](/learn/glossary#waku-message-payload-encryption) methods. :::info Waku lacks protocol-level message encryption because it does not know the communication parties. This design choice enhances Waku's encryption flexibility, encouraging developers to freely use custom protocols or [Waku message payload encryption](/learn/glossary#waku-message-payload-encryption) methods. @@ -37,7 +37,7 @@ yarn add @waku/message-encryption ## Symmetric encryption -Symmetric encryption uses a single, shared key for message encryption and decryption. Use the `generateSymmetricKey()` function to generate a random symmetric key: +`Symmetric` encryption uses a single, shared key for message encryption and decryption. Use the `generateSymmetricKey()` function to generate a random symmetric key: ```js import { generateSymmetricKey } from "@waku/message-encryption"; @@ -46,7 +46,7 @@ import { generateSymmetricKey } from "@waku/message-encryption"; const symKey = generateSymmetricKey(); ``` -To send encrypted messages, create a symmetric message `encoder` and send the message as usual: +To send encrypted messages, create a `Symmetric` message `encoder` and send the message as usual: ```js import { createEncoder } from "@waku/message-encryption/symmetric"; @@ -79,7 +79,7 @@ await node.store.queryWithOrderedCallback([decoder], callback); ## ECIES encryption -ECIES encryption uses a public key for encryption and a private key for decryption. Use the `generatePrivateKey()` function to generate a random private key: +`ECIES` encryption uses a public key for encryption and a private key for decryption. Use the `generatePrivateKey()` function to generate a random private key: ```js import { generatePrivateKey, getPublicKey } from "@waku/message-encryption"; @@ -91,7 +91,7 @@ const privateKey = generatePrivateKey(); const publicKey = getPublicKey(privateKey); ``` -To send encrypted messages, create an ECIES message `encoder` with the public key and send the message as usual: +To send encrypted messages, create an `ECIES` message `encoder` with the public key and send the message as usual: ```js import { createEncoder } from "@waku/message-encryption/ecies"; @@ -106,7 +106,7 @@ const encoder = createEncoder({ await node.lightPush.send(encoder, { payload }); ``` -To decrypt the messages you receive, create an ECIES message `decoder` with the private key and process the messages as usual: +To decrypt the messages you receive, create an `ECIES` message `decoder` with the private key and process the messages as usual: ```js import { createDecoder } from "@waku/message-encryption/ecies"; @@ -122,6 +122,35 @@ await subscription.subscribe([decoder], callback); await node.store.queryWithOrderedCallback([decoder], callback); ``` +## Signing encrypted messages + +Message signing helps in proving the authenticity of received messages. By attaching a signature to a message, you can verify its origin and integrity with absolute certainty. + +The `sigPrivKey` option allows the `Symmetric` and `ECIES` message `encoders` to sign the message before encryption using an `ECDSA` private key: + +```js +import { generatePrivateKey } from "@waku/message-encryption"; +import { createEncoder as createSymmetricEncoder } from "@waku/message-encryption/symmetric"; +import { createEncoder as createECIESEncoder } from "@waku/message-encryption/ecies"; + +// Generate a random private key for signing messages +const sigPrivKey = generatePrivateKey(); + +// Create a symmetric encoder that signs messages +const symmetricEncoder = createSymmetricEncoder({ + contentTopic: contentTopic, // message content topic + symKey: symKey, // symmetric key for encrypting messages + sigPrivKey: sigPrivKey, // private key for signing messages before encryption +}); + +// Create an ECIES encoder that signs messages +const ECIESEncoder = createECIESEncoder({ + contentTopic: contentTopic, // message content topic + publicKey: publicKey, // ECIES public key for encrypting messages + sigPrivKey: sigPrivKey, // private key for signing messages before encryption +}); +``` + :::tip Congratulations! -You have successfully encrypted and decrypted your messages using `symmetric` and `ECIES` encryption methods. Have a look at the [flush-notes](https://github.com/waku-org/js-waku-examples/tree/master/examples/flush-notes) example for a working demo. +You have successfully encrypted, decrypted, and signed your messages using `symmetric` and `ECIES` encryption methods. Have a look at the [flush-notes](https://github.com/waku-org/js-waku-examples/tree/master/examples/flush-notes) example for a working demo. ::: \ No newline at end of file