vacp2p
/
rfc
mirror of https://github.com/vacp2p/rfc.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Feature/add private api (#277) 

* Add Private API
This commit is contained in:
Hanno Cornelius 2020-12-17 10:17:52 +02:00 committed by GitHub
parent 29400162d4
commit 4f95e7c0ce
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 82 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
specs/waku/v2/waku-v2-rpc-api.md
View File

@ -16,6 +16,8 @@ authors: Hanno Cornelius <hanno@status.im>
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

4
wordlist.txt
View File

@ -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