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.

  • Targetsjs, wasmJs
  • TransportWebSocket client only
  • CryptographyWebCrypto
  • EDHOC suites0–3, 6, 24

Prerequisites

  • A Kotlin Multiplatform project with a js or wasmJs target, 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-server in front of UDP devices.
  • The build sets no minimum browser version. Kotlin/Wasm needs a browser with WebAssembly garbage collection.

Install status

Usable from Kotlin only

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

  1. 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 wasmJs opt-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-server forwarding 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, @JsExport and TypeScript declarations, for use from JavaScript.
  • The proxy cross-test from a real browser, a client proxy setting, and the wasmJs WebSocket engine against a real server.
  • OSCORE over HTTP, and a size budget for the JavaScript bundle.

Troubleshooting

kcoap-transport-ktor has no variant for js
Browsers have no UDP or TCP sockets. Use kcoap-transport-ktor-websocket instead.
The WebSocket connection fails
The server must accept the subprotocol coap at /.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 a coaps+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