From 4f95e7c0ce1d55d9a84dae0da4084591e3658b7a Mon Sep 17 00:00:00 2001 From: Hanno Cornelius <68783915+jm-clius@users.noreply.github.com> Date: Thu, 17 Dec 2020 10:17:52 +0200 Subject: [PATCH] Feature/add private api (#277) * Add Private API --- specs/waku/v2/waku-v2-rpc-api.md | 78 ++++++++++++++++++++++++++++++++ wordlist.txt | 4 ++ 2 files changed, 82 insertions(+) diff --git a/specs/waku/v2/waku-v2-rpc-api.md b/specs/waku/v2/waku-v2-rpc-api.md index cb757b91..bbe3ae98 100644 --- a/specs/waku/v2/waku-v2-rpc-api.md +++ b/specs/waku/v2/waku-v2-rpc-api.md @@ -16,6 +16,8 @@ authors: Hanno Cornelius 1. [Relay API](#relay-api) 1. [Store API](#store-api) 1. [Filter API](#filter-api) + 1. [Admin API](#admin-api) + 1. [Private API](#private-api) 1. [Example usage](#example-usage) 1. [Changelog](#changelog) 1. [Copyright](#copyright) @@ -312,6 +314,82 @@ none #### Response - **`Array`[[`WakuPeer`](#WakuPeer)]** - Array of peers registered on this node +## Private API + +The Private API provides functionality to encrypt/decrypt `WakuMessage` payloads using either symmetric or asymmetric cryptography. This allows backwards compatibility with [Waku v1 nodes](https://github.com/vacp2p/specs/blob/master/specs/waku/v1/waku-1.md). +It is the API client's responsibility to keep track of the keys used for encrypted communication. Since keys must be cached by the client and provided to the node to encrypt/decrypt payloads, a Private API SHOULD NOT be exposed on non-local or untrusted nodes. + +### Types + +The following structured types are defined for use on the Private API: + +`KeyPair` is an `Object` containing the following fields: +| Field | Type | Inclusion | Description | +| ----: | :--: | :--: |----------- | +| `privateKey` | `String` | mandatory | Private key as hex encoded data string | +| `publicKey` | `String` | mandatory | Public key as hex encoded data string | + +#### KeyPair + +### `get_waku_v2_private_v1_symkey` + +Generates and returns a symmetric key that can be used for message encryption and decryption. + +#### Parameters + +none + +#### Response +- **`String`** - A new symmetric key as hex encoded data string + +### `get_waku_v2_private_v1_keypair` + +Generates and returns a public/private key pair that can be used for asymmetric message encryption and decryption. + +#### Parameters + +none + +#### Response +- **[`KeyPair`](#KeyPair)** - A new public/private key pair as hex encoded data strings + +### `post_waku_v2_private_v1_message` + +The `post_waku_v2_private_v1_message` method publishes a message to be relayed on a [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor). + +Before being relayed, the message payload is encrypted using either the supplied symmetric key or public key. The client MUST provide either a symmetric key or a public key. Only one of these keys SHOULD be provided. If both keys are provided, the server will default to symmetric key encryption. + +#### Parameters + +| Field | Type | Inclusion | Description | +| ----: | :--: | :--: |----------- | +| `topic` | `String` | mandatory | The [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor) being published on | +| `message` | [`WakuRelayMessage`](#WakuRelayMessage) | mandatory | The (unencrypted) `message` being relayed | +| `symkey` | `String` | conditional | The hex encoded symmetric key to use for payload encryption. This field MUST be included if symmetric key cryptography is selected | +| `publicKey` | `String` | conditional | The hex encoded public key to use for payload encryption. This field MUST be included if asymmetric key cryptography is selected | + +#### Response + +- **`Bool`** - `true` on success or an [error](https://www.jsonrpc.org/specification#error_object) on failure. + +### `get_waku_v2_private_v1_messages` + +The `get_waku_v2_private_v1_messages` method decrypts and returns a list of messages that were received on a subscribed [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor) after the last time this method was called. The server MUST respond with an [error](https://www.jsonrpc.org/specification#error_object) if no subscription exists for the polled `topic`. If no message has yet been received on the polled `topic`, the server SHOULD return an empty list. This method can be used to poll a `topic` for new messages. + +Before returning the messages, the server decrypts the message payloads using either the supplied symmetric key or private key. The client MUST provide either a symmetric key or a private key. Only one of these keys SHOULD be provided. If both keys are provided, the server will attempt decryption using the symmetric key. + +#### Parameters + +| Field | Type | Inclusion | Description | +| ----: | :--: | :--: |----------- | +| `topic` | `String` | mandatory | The [PubSub `topic`](https://github.com/libp2p/specs/blob/master/pubsub/README.md#the-topic-descriptor) to poll for the latest messages | +| `symkey` | `String` | conditional | The hex encoded symmetric key to use for payload decryption. This field MUST be included if symmetric key cryptography is selected | +| `privateKey` | `String` | conditional | The hex encoded private key to use for payload decryption. This field MUST be included if asymmetric key cryptography is selected | + +#### Response + +- **`Array`[[`WakuRelayMessage`](#WakuRelayMessage)]** - the latest `messages` on the polled `topic` or an [error](https://www.jsonrpc.org/specification#error_object) on failure. + # Example usage ## Store API diff --git a/wordlist.txt b/wordlist.txt index 11790f14..1dca5d42 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -37,6 +37,7 @@ DDoS De decrypt decrypted +decrypts dereference deserialized devp @@ -87,6 +88,7 @@ Kademlia keccak Keccak keypair +KeyPair kimdemey Lange libp @@ -109,6 +111,7 @@ mixnet mixnets Mscgen multiaddr +Multiaddress mvds NameInit NameUpdate @@ -194,6 +197,7 @@ underspecified unlinkability unencrypted unsynchronized +untrusted upgradability uuid UUID