From 649e484b620a2573d62695f9b90de12a0c961796 Mon Sep 17 00:00:00 2001 From: Vojtech Simetka Date: Mon, 15 Feb 2021 09:57:47 +0100 Subject: [PATCH 1/4] feat: documentation for PSS --- docs/user-documentation/pss.md | 173 ++++++++++++++++++++++++++++++++- sidebars.js | 3 +- 2 files changed, 174 insertions(+), 2 deletions(-) diff --git a/docs/user-documentation/pss.md b/docs/user-documentation/pss.md index ef8fc08b..2cad02a1 100644 --- a/docs/user-documentation/pss.md +++ b/docs/user-documentation/pss.md @@ -1,6 +1,5 @@ --- title: Postal Service over Swarm -hide_title: true id: pss slug: /pss sidebar_label: Postal Service over Swarm @@ -8,3 +7,175 @@ sidebar_label: Postal Service over Swarm import Tabs from '@theme/Tabs' import TabItem from '@theme/TabItem' + +Swarm provides the ability to send messages that appear to be normal Swarm traffic, but are in fact messages that may be received and decrypted to reveal their content only by the specific nodes they were intended to be received by. + +PSS provides a pub-sub facility that can be used for a variety of tasks. Nodes are able to listen to messages received for a specific topic in their nearest neighbourhood and create messages destined for another neighbourhood which are sent over the network using Swarm's usual data dissemination protocols. + +The intended use of PSS is to send one of encrypted or public communication with a publicly known identity (to for example initiate further communication directly). Due to the cost of mining the trojan chunks, it is not recommended to use as and instant messaging system. For the same reason, the API is disabled on public gateways. + +## Getting the relevant data +When you start `bee`, you may find all the necessary information in the log: +```sh +INFO using existing swarm network address: 9e2ebf266369090091620db013aab164afb1574aedb3fcc08ce8dc6e6f28ef54 +INFO swarm public key 03e0cee7e979fa99350fc2e2f8c81d857b525b710380f238742af269bb794dfd3c +INFO pss public key 02fa24cac43531176d21678900b37bd800c93da3b02c5e11572fb6a96ec49527fa +INFO using ethereum address 5f5505033e3b985b88e20616d95201596b463c9a +``` +Let's break it down: +- **Ethereum address** is the public address of your node wallet. Together with the corresponding private key, it is used for things such as making Ethereum transactions (receiving and sending ETH and BZZ); receiving, claiming and singing cheques and the Swarm network address is also derived from it. +- The **Swarm network address** defines your location in the kademlia and within the context of PSS is used for addressing the trojan chunks to you. In other words, others may use it to send you a message. +- **PSS public key** can be used by others to encrypt their messages for you. + + + +## Sending message + +To send data simply define a topic, prefix of the recipient's swarm network address (we recommend 4-6 character prefix length) and the data to be send. + + + + +```ts +/** + * @param {string} topic + * @param {string} targetPrefix + * @param {string|Uint8Array} data + * @param {string} encryptionKey + */ +bee.pssSend('topic', '9e2e', 'Hello!') +``` + + + + +```js +/** + * @param {string} topic + * @param {string} targetPrefix + * @param {string|Uint8Array} data + * @param {string} encryptionKey + */ +bee.pssSend('topic', '9e2e', 'Hello!') +``` + + + + +Optionally, if you want to encrypt the message, you may provide the recipient's PSS public key. + + + + +```ts +bee.pssSend( + 'topic', + '9e2e', + 'Encrypted Hello!', + '02fa24cac43531176d21678900b37bd800c93da3b02c5e11572fb6a96ec49527fa', +) +``` + + + + +```js +bee.pssSend( + 'topic', + '9e2e', + 'Encrypted Hello!', + '02fa24cac43531176d21678900b37bd800c93da3b02c5e11572fb6a96ec49527fa', +) +``` + + + + +## Retrieving message +As a recipient, you have two ways how to recieve the message. If you are expecting one off message (which is the intended PSS usecase to exchange credentials for further direct communication), you can use the `pssReceive` method. + + + + +```ts +const message = await bee.pssReceive('topic') + +console.log(new TextDecoder("utf-8").decode(message)) // prints the received message +``` + + + + +```js +const message = await bee.pssReceive('topic') + +console.log(new TextDecoder("utf-8").decode(message)) // prints the received message +``` + + + + +If you want to subscribe to multiple messagees, use the `pssSubscribe` method. + + + + + +```ts +const handler = { + onMessage: (message: Uint8Array) => {console.log(new TextDecoder("utf-8").decode(message))}, + onError: (error: BeeError) => {console.log(error)} +} + +// Subscribe +const subscription = bee.pssSubscribe('topic', handler) + +// Terminate the subscription +subscription.cancel() +``` + + + + +```js +const handler = { + onMessage: (message: Uint8Array) => {console.log(new TextDecoder("utf-8").decode(message))}, + onError: (error: BeeError) => {console.log(error)} +} + +// Subscribe +const subscription = bee.pssSubscribe('topic', handler) + +// Terminate the subscription +subscription.cancel() +``` + + + \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 6602c29e..1c8bf094 100644 --- a/sidebars.js +++ b/sidebars.js @@ -8,7 +8,8 @@ module.exports = { 'user-documentation/getting-started', 'user-documentation/upload-download', 'user-documentation/track-upload', - // 'user-documentation/pss', + 'user-documentation/pss', + // 'user-documentation/feeds', ], collapsed: false }, From 21a7480c8848506cdc53c370a89c00cac9902680 Mon Sep 17 00:00:00 2001 From: Vojtech Simetka Date: Thu, 18 Feb 2021 18:05:17 +0100 Subject: [PATCH 2/4] chore: grammar suggestion by @significance Co-authored-by: significance --- docs/user-documentation/pss.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-documentation/pss.md b/docs/user-documentation/pss.md index 2cad02a1..8ec25bb4 100644 --- a/docs/user-documentation/pss.md +++ b/docs/user-documentation/pss.md @@ -107,7 +107,7 @@ bee.pssSend( ## Retrieving message -As a recipient, you have two ways how to recieve the message. If you are expecting one off message (which is the intended PSS usecase to exchange credentials for further direct communication), you can use the `pssReceive` method. +As a recipient, you have two ways how to receive the message. If you are expecting one off message (which is the intended PSS use case to exchange credentials for further direct communication), you can use the `pssReceive` method. - \ No newline at end of file + From 31f2feafe713fe0550295417b0e36b4d7419b360 Mon Sep 17 00:00:00 2001 From: Vojtech Simetka Date: Thu, 18 Feb 2021 18:10:11 +0100 Subject: [PATCH 3/4] chore: apply language suggestions from code review but @agazso --- docs/user-documentation/pss.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-documentation/pss.md b/docs/user-documentation/pss.md index 8ec25bb4..98f05614 100644 --- a/docs/user-documentation/pss.md +++ b/docs/user-documentation/pss.md @@ -8,11 +8,11 @@ sidebar_label: Postal Service over Swarm import Tabs from '@theme/Tabs' import TabItem from '@theme/TabItem' -Swarm provides the ability to send messages that appear to be normal Swarm traffic, but are in fact messages that may be received and decrypted to reveal their content only by the specific nodes they were intended to be received by. +Swarm provides the ability to send messages that appear to be normal Swarm traffic, but are in fact messages that may be received and decrypted to reveal their content only to specific nodes that were intended to receive them. PSS provides a pub-sub facility that can be used for a variety of tasks. Nodes are able to listen to messages received for a specific topic in their nearest neighbourhood and create messages destined for another neighbourhood which are sent over the network using Swarm's usual data dissemination protocols. -The intended use of PSS is to send one of encrypted or public communication with a publicly known identity (to for example initiate further communication directly). Due to the cost of mining the trojan chunks, it is not recommended to use as and instant messaging system. For the same reason, the API is disabled on public gateways. +The intended use of PSS is to communicate privately with a publicly known identity (to for example initiate further communication directly). Due to the cost of mining the trojan chunks, it is not recommended to use as an instant messaging system. ## Getting the relevant data When you start `bee`, you may find all the necessary information in the log: From f600a2dd18d1e18d586741de8e1e278622a883e2 Mon Sep 17 00:00:00 2001 From: Vojtech Simetka Date: Thu, 18 Feb 2021 18:29:20 +0100 Subject: [PATCH 4/4] chore: added warning about privacy for unencrypted PSS communication --- docs/user-documentation/pss.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/user-documentation/pss.md b/docs/user-documentation/pss.md index 98f05614..d9648dd7 100644 --- a/docs/user-documentation/pss.md +++ b/docs/user-documentation/pss.md @@ -35,6 +35,9 @@ This section will need a lot of love and testing, probably should be in some adv ## Sending message To send data simply define a topic, prefix of the recipient's swarm network address (we recommend 4-6 character prefix length) and the data to be send. +:::caution Your communication privacy may be at risk +When sending PSS messages without encryption key, any Bee node through which the trojan chunk passes would be able to read the message. +::: -Optionally, if you want to encrypt the message, you may provide the recipient's PSS public key. +If you want to encrypt the message, you may provide the recipient's PSS public key.