Encrypt, Decrypt, and Sign Your Messages

This guide provides detailed steps to use the @waku/message-encryption package to encrypt, decrypt, and sign your messages using Waku message payload encryption methods.

info

Waku uses libp2p noise encryption for node-to-node connections. However, no default encryption method is applied to the data sent over the network. This design choice enhances Waku's encryption flexibility, encouraging developers to freely use custom protocols or Waku message payload encryption methods.

Installation

Install the required packages for integrating @waku/message-encryption using your preferred package manager:

NPM

npm install @waku/message-encryption @waku/utils

Yarn

yarn add @waku/message-encryption @waku/utils

Symmetric encryption

Symmetric encryption uses a single, shared key for message encryption and decryption. Use the generateSymmetricKey() function to generate a random symmetric key:

import { generateSymmetricKey } from "@waku/message-encryption";

// Generate a random symmetric key
const symmetricKey = generateSymmetricKey();

To send encrypted messages, create a Symmetric message encoder and send the message as usual:

Sender client

import { createEncoder } from "@waku/message-encryption/symmetric";

// Create a symmetric message encoder
const encoder = createEncoder({
    contentTopic: contentTopic, // message content topic
    symKey: symmetricKey, // symmetric key for encrypting messages
});

// Send the message using Light Push
await node.lightPush.send(encoder, { payload });

To decrypt the messages you receive, create a symmetric message decoder and process the messages as usual:

Receiver client

import { createDecoder } from "@waku/message-encryption/symmetric";

// Create a symmetric message decoder
const decoder = createDecoder(contentTopic, symmetricKey);

// Receive messages from a Filter subscription
await subscription.subscribe([decoder], callback);

// Retrieve messages from Store peers
await node.store.queryWithOrderedCallback([decoder], callback);

tip

The symmetric key exchange between users can happen through an out-of-band method. For example, where the key is embedded within the URL shared by a user to access a specific resource.

ECIES encryption

ECIES encryption uses a public key for encryption and a private key for decryption. Use the generatePrivateKey() function to generate a random ECDSA private key:

import { generatePrivateKey, getPublicKey } from "@waku/message-encryption";

// Generate a random ECDSA private key, keep secure
const privateKey = generatePrivateKey();

// Generate a public key from the private key, provide to the sender
const publicKey = getPublicKey(privateKey);

To send encrypted messages, create an ECIES message encoder with the public key and send the message as usual:

Sender client

import { createEncoder } from "@waku/message-encryption/ecies";

// Create an ECIES message encoder
const encoder = createEncoder({
    contentTopic: contentTopic, // message content topic
    publicKey: publicKey, // ECIES public key for encrypting messages
});

// Send the message using Light Push
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:

Receiver client

import { createDecoder } from "@waku/message-encryption/ecies";

// Create an ECIES message decoder
const decoder = createDecoder(contentTopic, privateKey);

// Receive messages from a Filter subscription
await subscription.subscribe([decoder], callback);

// Retrieve messages from Store peers
await node.store.queryWithOrderedCallback([decoder], callback);

tip

Users can share their public key through broadcasting or out-of-band methods, such as embedding it in a URL or sending an unencrypted message on another content topic for others to retrieve.

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.

info

Signing messages is only possible when encrypted, but if your application does not require encryption, you can generate a symmetric key through hardcoded or deterministic methods using information available to all users.

The sigPrivKey parameter allows the Symmetric and ECIES message encoders to sign the message before encryption using an ECDSA private key:

Alice (sender) client

import { generatePrivateKey, getPublicKey } 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 ECDSA private key for signing messages
// ECIES encryption and message signing both use ECDSA keys
// For this example, we'll call the sender of the message Alice
const alicePrivateKey = generatePrivateKey();
const alicePublicKey = getPublicKey(alicePrivateKey);

// Create a symmetric encoder that signs messages
const symmetricEncoder = createSymmetricEncoder({
    contentTopic: contentTopic, // message content topic
    symKey: symmetricKey, // symmetric key for encrypting messages
    sigPrivKey: alicePrivateKey, // 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: alicePrivateKey, // private key for signing messages before encryption
});

// Send and receive your messages as usual with Light Push and Filter
await subscription.subscribe([symmetricEncoder], callback);
await node.lightPush.send(symmetricEncoder, { payload });

await subscription.subscribe([ECIESEncoder], callback);
await node.lightPush.send(ECIESEncoder, { payload });

You can extract the signature and its public key (signaturePublicKey) from the DecodedMessage and compare it with the expected public key or use the verifySignature() function to verify the message origin:

Bob (receiver) client

import { generatePrivateKey } from "@waku/message-encryption";
import { createEncoder } from "@waku/message-encryption/symmetric";

// Generate a random private key for signing messages
// For this example, we'll call the receiver of the message Bob
const bobPrivateKey = generatePrivateKey();

// Create an encoder that signs messages
const encoder = createEncoder({
    contentTopic: contentTopic,
    symKey: symmetricKey,
    sigPrivKey: bobPrivateKey,
});

// Modify the callback function to verify message signature
const callback = (wakuMessage) => {
    // Extract the message signature and public key of the signature
    // You can compare the signaturePublicKey with Alice public key
    const signature = wakuMessage.signature;
    const signaturePublicKey = wakuMessage.signaturePublicKey;

    // Verify the message was actually signed and sent by Alice
    // Alice's public key can be gotten from broadcasting or out-of-band methods
    if (wakuMessage.verifySignature(alicePublicKey)) {
        console.log("This message was signed by Alice");
    } else {
        console.log("This message was NOT signed by Alice");
    }
};

await subscription.subscribe([encoder], callback);

Storing encryption keys

We used randomly generated keys for encryption and message signing in the provided examples, but real-world applications require consistent keys among client restarts. Have a look at the Key Pair Handling example, which demonstrates the secure storage and retrieval of key information from local storage using Subtle Crypto.

If you need a simple way to store your keys in hexadecimal format across your application, you can use the @waku/utils package:

import { bytesToHex, hexToBytes } from "@waku/utils/bytes";

// Generate random symmetric and private keys
const symmetricKey = generateSymmetricKey();
const privateKey = generatePrivateKey();

// Store the keys in hexadecimal format
const symmetricKeyHex = bytesToHex(symmetricKey);
const privateKeyHex = bytesToHex(privateKey);

// Restore the keys from hexadecimal format
const restoredSymmetricKey = hexToBytes(symmetricKeyHex);
const restoredPrivateKey = hexToBytes(privateKeyHex);

Congratulations!

You have successfully encrypted, decrypted, and signed your messages using Symmetric and ECIES encryption methods. Have a look at the eth-pm example for a working demo.