From d4fd2e590fb7c439b0983743d220d81ae812e7ae Mon Sep 17 00:00:00 2001 From: Pranav Ghorpade Date: Thu, 12 Feb 2026 17:49:19 +0000 Subject: [PATCH 1/2] docs(binding-coap): document PSK usage with CoAPs Add example and explanation for configuring PSK security scheme in CoapsClient. Closes #954 Signed-off-by: Pranav Ghorpade --- packages/binding-coap/README.md | 59 +++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/packages/binding-coap/README.md b/packages/binding-coap/README.md index 1562f44ec..0feb619b6 100644 --- a/packages/binding-coap/README.md +++ b/packages/binding-coap/README.md @@ -94,6 +94,65 @@ servient.start().then((WoT) => { }); ``` +## Using CoAPs with PSK + +The CoAP binding also supports secure CoAP (`coaps://`) using DTLS with the +`psk` (Pre-Shared Key) security scheme. + +Currently, PSK support is implemented in the `CoapsClient` and can be +configured via the Thing Description and client credentials. + +### Thing Description Example + +To use PSK, the Thing Description must define a `psk` security scheme: + +```json +{ + "securityDefinitions": { + "psk_sc": { + "scheme": "psk" + } + }, + "security": ["psk_sc"] +} +``` + +### Client Configuration Example + +On the client side, credentials must be provided via the Servient +using `addCredentials()`. The credentials are associated with the +Thing's `id` and are automatically applied based on the TD security +configuration. + +```js +const { Servient } = require("@node-wot/core"); +const { CoapsClientFactory } = require("@node-wot/binding-coap"); + +const servient = new Servient(); +servient.addClientFactory(new CoapsClientFactory()); + +servient.start().then(async (WoT) => { + const td = await WoT.requestThingDescription("coaps://example.com/secure-thing"); + + // Configure PSK credentials for this Thing + servient.addCredentials({ + [td.id]: { + identity: "Client_identity", + psk: "secretPSK", + }, + }); + + const thing = await WoT.consume(td); + + await thing.invokeAction("someAction"); +}); +``` + +The `identity` and `psk` values must match the configuration of the +CoAPs server. + +> **Note:** Only the psk security scheme is currently supported for CoAPs. + ### More Details See From 477dc140f333566b5d4112d408c2a41c8178475d Mon Sep 17 00:00:00 2001 From: Pranav Ghorpade Date: Fri, 13 Feb 2026 17:13:09 +0000 Subject: [PATCH 2/2] docs(binding-coap): document PSK usage with CoAPs Add example and explanation for configuring PSK security scheme in CoapsClient. Closes #954 Signed-off-by: Pranav Ghorpade --- packages/binding-coap/README.md | 131 ++++++++++++++++++-------------- 1 file changed, 72 insertions(+), 59 deletions(-) diff --git a/packages/binding-coap/README.md b/packages/binding-coap/README.md index 0feb619b6..087f7b103 100644 --- a/packages/binding-coap/README.md +++ b/packages/binding-coap/README.md @@ -52,6 +52,78 @@ servient }); ``` +## Using PSK with CoAPs (DTLS) + +The CoAP binding also supports secure communication over `coaps://` using DTLS with Pre-Shared Keys (PSK). + +To use PSK security, define a `psk` security scheme in the Thing Description and provide the credentials when consuming the Thing. + +### Thing Description Example (PSK) + +```json +{ + "title": "SecureThing", + "securityDefinitions": { + "psk_sc": { + "scheme": "psk" + } + }, + "security": ["psk_sc"], + "properties": { + "count": { + "type": "integer", + "forms": [ + { + "href": "coaps://localhost:5684/count" + } + ] + } + } +} +``` + +### Client Example with PSK + +```js +const { Servient } = require("@node-wot/core"); +const { CoapClientFactory } = require("@node-wot/binding-coap"); + +const servient = new Servient(); +servient.addClientFactory(new CoapClientFactory()); + +servient + .start() + .then(async (WoT) => { + try { + const td = await WoT.requestThingDescription("coaps://localhost:5684/secureThing"); + const thing = await WoT.consume(td); + + // configure PSK security + thing.setSecurity( + td.securityDefinitions, + { + identity: "Client_identity", + psk: "secretPSK" + } + ); + + const value = await thing.readProperty("count"); + console.log("count value is:", await value.value()); + } catch (err) { + console.error("Script error:", err); + } + }) + .catch((err) => { + console.error("Start error:", err); + }); +``` + +### Notes + +- The `identity` must match the server configuration. +- The `psk` must match the server's configured secret. +- Currently, only the `psk` security scheme is supported for `coaps://` in this binding. + ### Server Example The server example produces a thing that allows for setting a property `count`. The thing is reachable through CoAP. @@ -94,65 +166,6 @@ servient.start().then((WoT) => { }); ``` -## Using CoAPs with PSK - -The CoAP binding also supports secure CoAP (`coaps://`) using DTLS with the -`psk` (Pre-Shared Key) security scheme. - -Currently, PSK support is implemented in the `CoapsClient` and can be -configured via the Thing Description and client credentials. - -### Thing Description Example - -To use PSK, the Thing Description must define a `psk` security scheme: - -```json -{ - "securityDefinitions": { - "psk_sc": { - "scheme": "psk" - } - }, - "security": ["psk_sc"] -} -``` - -### Client Configuration Example - -On the client side, credentials must be provided via the Servient -using `addCredentials()`. The credentials are associated with the -Thing's `id` and are automatically applied based on the TD security -configuration. - -```js -const { Servient } = require("@node-wot/core"); -const { CoapsClientFactory } = require("@node-wot/binding-coap"); - -const servient = new Servient(); -servient.addClientFactory(new CoapsClientFactory()); - -servient.start().then(async (WoT) => { - const td = await WoT.requestThingDescription("coaps://example.com/secure-thing"); - - // Configure PSK credentials for this Thing - servient.addCredentials({ - [td.id]: { - identity: "Client_identity", - psk: "secretPSK", - }, - }); - - const thing = await WoT.consume(td); - - await thing.invokeAction("someAction"); -}); -``` - -The `identity` and `psk` values must match the configuration of the -CoAPs server. - -> **Note:** Only the psk security scheme is currently supported for CoAPs. - ### More Details See