mirror of https://github.com/vacp2p/rfc.git
fix(WAKU2-RPC): encode waku message payloads in base64 (#572)
This commit is contained in:
Lorenzo Delgado
GitHub
parent
ab661c8276
commit
1e9e985d67
|
|
@ -49,7 +49,7 @@ Refer to [`Waku Message` specification](/spec/14/) for more information.
|
|||
|
||||
| Field | Type | Inclusion | Description |
|
||||
| ---: | :---: | :---: | --- |
|
||||
| `payload` | `String` | mandatory | The message payload as a hex encoded data string |
|
||||
| `payload` | `String` | mandatory | The message payload as a **base64** encoded data string |
|
||||
| `contentTopic` | `String` | optional | Message content topic for optional content-based filtering |
|
||||
| `version` | `Number` | optional | Message version. Used to indicate type of payload encryption. Default version is 0 (no payload encryption). |
|
||||
| `timestamp` | `Number` | optional | The time at which the message is generated by its sender. This field holds the Unix epoch time in nanoseconds as a 64-bits integer value. |
|
||||
|
|
@ -117,23 +117,6 @@ none
|
|||
|
||||
Refer to the [Waku Relay specification](https://github.com/vacp2p/specs/blob/master/specs/waku/v2/waku-relay.md) for more information on the relaying of messages.
|
||||
|
||||
### Types
|
||||
|
||||
The following structured types are defined for use on the Relay API:
|
||||
|
||||
#### WakuRelayMessage
|
||||
|
||||
`WakuRelayMessage` is an `Object` containing the following fields:
|
||||
|
||||
| Field | Type | Inclusion | Description |
|
||||
| ----: | :---: | :---: | ----------- |
|
||||
| `payload` | `String` | mandatory | The payload being relayed as a hex encoded data string |
|
||||
| `contentTopic` | `String` | optional | Message content topic for optional content-based filtering |
|
||||
| `timestamp` | `Number` | optional | The time at which the message is generated by its sender. This field holds the Unix epoch time in nanoseconds as a 64-bits integer value. |
|
||||
| `ephemeral` | `Boolean` | optional | This flag indicates the transient nature of the message. |
|
||||
|
||||
> **_NOTE:_** `WakuRelayMessage` maps directly to a [`WakuMessage`](#wakumessage), except that the latter contains an explicit message `version`. For `WakuRelay` purposes, the versioning is handled by the API.
|
||||
|
||||
### `post_waku_v2_relay_v1_message`
|
||||
|
||||
The `post_waku_v2_relay_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)
|
||||
|
|
@ -143,7 +126,7 @@ The `post_waku_v2_relay_v1_message` method publishes a message to be relayed on
|
|||
| 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 `message` being relayed |
|
||||
| `message` | [`WakuMessage`](#wakumessage) | mandatory | The `message` being relayed |
|
||||
|
||||
#### Response
|
||||
|
||||
|
|
@ -191,6 +174,117 @@ The `get_waku_v2_relay_v1_messages` method returns a list of messages that were
|
|||
|
||||
- **`Array`[[`WakuMessage`](#wakumessage)]** - the latest `messages` on the polled `topic` or an [error](https://www.jsonrpc.org/specification#error_object) on failure.
|
||||
|
||||
## Relay 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
|
||||
|
||||
`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 |
|
||||
|
||||
### `get_waku_v2_private_v1_symmetric_key`
|
||||
|
||||
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_asymmetric_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_symmetric_message`
|
||||
|
||||
The `post_waku_v2_private_v1_symmetric_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 the supplied symmetric key. The client MUST provide a 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) being published on |
|
||||
| `message` | [`WakuMessage`](#wakumessage) | mandatory | The (unencrypted) `message` being relayed |
|
||||
| `symkey` | `String` | mandatory | The hex encoded symmetric key to use for payload encryption. This field MUST be included if symmetric key cryptography is selected |
|
||||
|
||||
#### Response
|
||||
|
||||
- **`Bool`** - `true` on success or an [error](https://www.jsonrpc.org/specification#error_object) on failure.
|
||||
|
||||
### `post_waku_v2_private_v1_asymmetric_message`
|
||||
|
||||
The `post_waku_v2_private_v1_asymmetric_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 the supplied public key. The client MUST provide a public 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) being published on |
|
||||
| `message` | [`WakuMessage`](#wakumessage) | mandatory | The (unencrypted) `message` being relayed |
|
||||
| `publicKey` | `String` | mandatory | 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_symmetric_messages`
|
||||
|
||||
The `get_waku_v2_private_v1_symmetric_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 the supplied symmetric key. The client MUST provide a 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` | mandatory | The hex encoded symmetric key to use for payload decryption. This field MUST be included if symmetric key cryptography is selected |
|
||||
|
||||
#### Response
|
||||
|
||||
- **`Array`[[`WakuMessage`](#wakumessage)]** - the latest `messages` on the polled `topic` or an [error](https://www.jsonrpc.org/specification#error_object) on failure.
|
||||
|
||||
### `get_waku_v2_private_v1_asymmetric_messages`
|
||||
|
||||
The `get_waku_v2_private_v1_asymmetric_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 the supplied private key. The client MUST provide a private 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 |
|
||||
| `privateKey` | `String` | mandatory | The hex encoded private key to use for payload decryption. This field MUST be included if asymmetric key cryptography is selected |
|
||||
|
||||
#### Response
|
||||
|
||||
- **`Array`[[`WakuMessage`](#wakuymessage)]** - the latest `messages` on the polled `topic` or an [error](https://www.jsonrpc.org/specification#error_object) on failure.
|
||||
|
||||
|
||||
## Store API
|
||||
|
||||
Refer to the [Waku Store specification](https://github.com/vacp2p/specs/blob/master/specs/waku/v2/waku-store.md) for more information on message history retrieval.
|
||||
|
|
@ -358,116 +452,6 @@ The `post_waku_v2_admin_v1_peers` method connects a node to a list of peers.
|
|||
- **`Bool`** - `true` on success or an [error](https://www.jsonrpc.org/specification#error_object) on failure.
|
||||
|
||||
|
||||
## 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
|
||||
|
||||
`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 |
|
||||
|
||||
### `get_waku_v2_private_v1_symmetric_key`
|
||||
|
||||
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_asymmetric_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_symmetric_message`
|
||||
|
||||
The `post_waku_v2_private_v1_symmetric_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 the supplied symmetric key. The client MUST provide a 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) being published on |
|
||||
| `message` | [`WakuRelayMessage`](#wakurelaymessage) | mandatory | The (unencrypted) `message` being relayed |
|
||||
| `symkey` | `String` | mandatory | The hex encoded symmetric key to use for payload encryption. This field MUST be included if symmetric key cryptography is selected |
|
||||
|
||||
#### Response
|
||||
|
||||
- **`Bool`** - `true` on success or an [error](https://www.jsonrpc.org/specification#error_object) on failure.
|
||||
|
||||
### `post_waku_v2_private_v1_asymmetric_message`
|
||||
|
||||
The `post_waku_v2_private_v1_asymmetric_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 the supplied public key. The client MUST provide a public 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) being published on |
|
||||
| `message` | [`WakuRelayMessage`](#wakurelaymessage) | mandatory | The (unencrypted) `message` being relayed |
|
||||
| `publicKey` | `String` | mandatory | 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_symmetric_messages`
|
||||
|
||||
The `get_waku_v2_private_v1_symmetric_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 the supplied symmetric key. The client MUST provide a 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` | mandatory | The hex encoded symmetric key to use for payload decryption. This field MUST be included if symmetric 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.
|
||||
|
||||
### `get_waku_v2_private_v1_asymmetric_messages`
|
||||
|
||||
The `get_waku_v2_private_v1_asymmetric_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 the supplied private key. The client MUST provide a private 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 |
|
||||
| `privateKey` | `String` | mandatory | 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
|
||||
|
|
@ -505,23 +489,17 @@ This method is part of the `store` API and the specific resources to retrieve ar
|
|||
"result": {
|
||||
"messages": [
|
||||
{
|
||||
"payload": [
|
||||
1
|
||||
],
|
||||
"payload": dGVzdDE,
|
||||
"contentTopic": "/waku/2/default-content/proto",
|
||||
"version": 0
|
||||
},
|
||||
{
|
||||
"payload": [
|
||||
2
|
||||
],
|
||||
"payload": dGVzdDI,
|
||||
"contentTopic": "/waku/2/default-content/proto",
|
||||
"version": 0
|
||||
},
|
||||
{
|
||||
"payload": [
|
||||
3
|
||||
],
|
||||
"payload": dGVzdDM,
|
||||
"contentTopic": "/waku/2/default-content/proto",
|
||||
"version": 0
|
||||
}
|
||||
|
|
@ -567,16 +545,12 @@ This method is part of the `store` API and the specific resources to retrieve ar
|
|||
"result": {
|
||||
"messages": [
|
||||
{
|
||||
"payload": [
|
||||
2
|
||||
],
|
||||
"payload": dGVzdDI,
|
||||
"contentTopic": "/waku/2/default-content/proto",
|
||||
"version": 0
|
||||
},
|
||||
{
|
||||
"payload": [
|
||||
3
|
||||
],
|
||||
"payload": dGVzdDM,
|
||||
"contentTopic": "/waku/2/default-content/proto",
|
||||
"version": 0
|
||||
}
|
||||
|
|
@ -633,12 +607,10 @@ This method is part of the `store` API and the specific resources to retrieve ar
|
|||
"result": {
|
||||
"messages": [
|
||||
{
|
||||
"payload": [
|
||||
1
|
||||
],
|
||||
"payload": dGVzdDE,
|
||||
"contentTopic": "/waku/2/default-content/proto",
|
||||
"version": 0
|
||||
}
|
||||
},
|
||||
],
|
||||
"pagingInfo": {
|
||||
"pageSize": 2,
|
||||
|
|
|
|||
Loading…
Reference in New Issue