Get started · Browsers
Browsers, with Kotlin/JS and Kotlin/Wasm
Browsers have no UDP and no TCP, so a browser speaks CoAP over WebSockets, to a server or to a proxy that forwards to devices. OSCORE and EDHOC run in the page and stay end to end across the proxy.
- Targets
js,wasmJs - TransportWebSocket client only
- CryptographyWebCrypto
- EDHOC suites0–3, 6, 24
Prerequisites
- A Kotlin Multiplatform project with a
jsorwasmJstarget, on Kotlin 2.3 or newer; the samples use 2.4.21, the version kcoap is built with. - A JDK 17 or newer, to run Gradle.
- A CoAP server that speaks WebSockets: a kcoap server on the JVM or Linux, as below, or a proxy such as libcoap’s
coap-serverin front of UDP devices. - The build sets no minimum browser version. Kotlin/Wasm needs a browser with WebAssembly garbage collection.
Install status
kcoap 0.1.0 is on Maven Central, its js and wasmJs artifacts included. It has no npm package and no TypeScript declarations, so your browser code is Kotlin/JS or Kotlin/Wasm. CI runs the common tests on Node.js, whose WebCrypto is the browsers’ API, and the js WebSocket client in headless Chrome against a JVM server. The wasmJs WebSocket engine has not run against a real server yet.
Set up
-
Create the build file
The WebSocket client is the only transport here: leave out
kcoap-transport-ktor, which builds no web targets. The bill of materials,kcoap-bom, sets one version for every kcoap module, so the modules name none.Kotlin DSL
build.gradle.kts
import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl plugins { kotlin("multiplatform") version "2.4.21" } repositories { mavenCentral() } kotlin { js { browser() binaries.executable() } @OptIn(ExperimentalWasmDsl::class) wasmJs { browser() binaries.executable() } sourceSets { commonMain.dependencies { val bom = "dev.kcoap:kcoap-bom:0.1.0" implementation(project.dependencies.platform(bom)) implementation("dev.kcoap:kcoap-coap") implementation("dev.kcoap:kcoap-transport-ktor-websocket") // WebCrypto underneath implementation("dev.kcoap:kcoap-crypto-default") // EDHOC, and OSCORE with it implementation("dev.kcoap:kcoap-edhoc-oscore") } } }Version catalog
gradle/libs.versions.toml
[versions] kotlin = "2.4.21" kcoap = "0.1.0" [libraries] kcoap-bom = { module = "dev.kcoap:kcoap-bom", version.ref = "kcoap" } kcoap-coap = { module = "dev.kcoap:kcoap-coap" } kcoap-transport-ktor-websocket = { module = "dev.kcoap:kcoap-transport-ktor-websocket" } kcoap-crypto-default = { module = "dev.kcoap:kcoap-crypto-default" } kcoap-edhoc-oscore = { module = "dev.kcoap:kcoap-edhoc-oscore" } [bundles] kcoap-web = [ "kcoap-coap", "kcoap-transport-ktor-websocket", "kcoap-crypto-default", "kcoap-edhoc-oscore", ] [plugins] kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }build.gradle.kts
import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl plugins { alias(libs.plugins.kotlin.multiplatform) } repositories { mavenCentral() } kotlin { js { browser() binaries.executable() } @OptIn(ExperimentalWasmDsl::class) wasmJs { browser() binaries.executable() } sourceSets { commonMain.dependencies { implementation(project.dependencies.platform(libs.kcoap.bom)) implementation(libs.bundles.kcoap.web) } } }A standard Kotlin Multiplatform build file, with the
wasmJsopt-in kcoap’s own build uses; kcoap’s coordinates are checked. kcoap’s repository has no browser application that builds this file.
First client and server
A browser cannot accept connections, so the server runs elsewhere. For a first try, run a kcoap server with a WebSocket listener on the JVM or Linux on your machine. It needs kcoap-transport-ktor-websocket-server and io.ktor:ktor-server-cio:3.6.1:
Server.kt (on the JVM)
val listener = KtorWebSocketListener.start(CIO, "127.0.0.1", 8080)
val server = CoapServer(listOf(listener), scope) {
resource("hello") {
get { CoapResponse.content("Hello over ${peer::class.simpleName}") }
}
}The WebSocket half of the JVM guide’s TCP and WebSocket server, which CI compiles and runs.
The browser client opens a WebSocket to /.well-known/coap with the subprotocol coap and asks for the resource:
src/commonMain/kotlin/Main.kt
import dev.kcoap.coap.client.CoapClient
import dev.kcoap.transport.ktor.websocket.KtorWebSocketConnector
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.launch
fun main() {
val scope = CoroutineScope(Dispatchers.Default + SupervisorJob())
scope.launch {
val client = CoapClient(listOf(KtorWebSocketConnector()), scope)
// Hello over WebSocket
println(client.get("coap+ws://127.0.0.1:8080/hello").payloadAsText())
client.close()
}
}The kcoap names are checked against the sources, and the client calls are the guide’s. The browser entry point, a scope launched from a plain main, is not exercised by kcoap’s repository.
Run it with the Kotlin Gradle plugin’s development server, ./gradlew jsBrowserDevelopmentRun or wasmJsBrowserDevelopmentRun, and open the browser console. A page served over HTTPS can open only wss:// WebSockets, so a deployed page uses coaps+ws:// URIs, with TLS from the browser.
To observe a resource, collect the cold Flow that client.observe(uri) returns; it registers when collected and deregisters when the collector stops, for example after take(3).
EDHOC and OSCORE in the page
The client half of EDHOC, then OSCORE, is the same as on any platform; the client uses KtorWebSocketConnector() and a coaps+ws:// URI. Use cipher suite 2 (P-256): it needs neither X25519, Ed25519 nor ChaCha20-Poly1305, so every browser runs it.
Secure.kt
val security = PeerSecurity()
val client = CoapClient(
listOf(KtorWebSocketConnector()),
scope,
CoapClientConfig { this.security = security },
)
val gateway = CoapUri.parse("coaps+ws://gateway.example")
val (session, protection) =
EdhocClientHandshake.over(client, gateway, initiatorConfig, crypto)
.runCombined()
security.install(client, gateway, protection)
println(client.get("coaps+ws://gateway.example/lights").payloadAsText())The README’s quick start with the WebSocket connector; names checked. EDHOC over a real WebSocket in a browser has not run anywhere yet: the full-stack EDHOC test runs on js and wasmJs on Node.js, over the in-memory network.
- Prefer EDHOC to pre-shared keys in a browser. Pre-shared OSCORE keys need durable sequence numbers, and a user can clear a site’s storage at any time. The IndexedDB recipe exists, but is not compiled or tested.
- Through a proxy, such as libcoap’s
coap-serverforwarding to UDP devices, OSCORE and EDHOC stay end to end; TLS ends at the proxy. CI runs this path with a WebSocket-only kcoap client on the JVM through libcoap 4.3.5b’s forward-proxy to a UDP device, with OSCORE, EDHOC and the combined request; not yet from a real browser. kcoap’s client has no proxy setting yet: the test adds the Proxy-Scheme and Uri-Host options itself. - Limits of libcoap’s proxy (ADR 0009): devices must listen on port 5683; request bodies must fit one message on each side, so post-quantum EDHOC does not cross it; and every browser behind it is one peer to the device, so EDHOC’s per-peer limits cover the whole gateway.
Platform notes
What WebCrypto lacks
- ChaCha20-Poly1305, so EDHOC suites 4 and 5 are neither offered nor accepted in a browser.
- AES-ECB: the AES block under CCM comes from AES-CTR, one asynchronous call per block.
- 192-bit AES keys in Chromium, and X25519 and Ed25519 in browsers that predate them.
- ML-KEM and ML-DSA: no post-quantum EDHOC in a browser yet.
kcoap asks the backend before it offers anything: crypto.supports(...) and CipherSuite.isSupportedBy(crypto, method) answer the same question on every platform. How capability checks work.
Not done yet in browsers
- An npm package,
@JsExportand TypeScript declarations, for use from JavaScript. - The proxy cross-test from a real browser, a client proxy setting, and the
wasmJsWebSocket engine against a real server. - OSCORE over HTTP, and a size budget for the JavaScript bundle.
Troubleshooting
kcoap-transport-ktorhas no variant forjs- Browsers have no UDP or TCP sockets. Use
kcoap-transport-ktor-websocketinstead. - The WebSocket connection fails
- The server must accept the subprotocol
coapat/.well-known/coap(RFC 8323). kcoap’s listener and libcoap’s WebSocket server do. - The browser refuses a
ws://connection - A page served over HTTPS may open only
wss://. Use acoaps+ws://URI with a server behind TLS. - EDHOC finds no common cipher suite
- Offer suite 2. Suites 4 and 5 never run in a browser, and 0 and 1 need X25519 and Ed25519.
Next steps
- Architecture: browsers, with the proxy setup and the WebCrypto table.
- The WebSocket client module: engines and the subprotocol.
- Features: what kcoap implements and how it is checked.