Get started · Linux

Linux gateways

kcoap compiles to a native Linux executable for x86-64, with OpenSSL 3 linked in: the gateway needs neither a JVM nor a system OpenSSL. The same common code as everywhere else, with UDP, TCP and WebSockets.

  • TargetlinuxX64
  • TransportsUDP, TCP, WebSocket client and server
  • CryptographyOpenSSL 3, linked in
  • ARM gatewaysNo linuxArm64 yet

Prerequisites

  • An x86-64 Linux machine to build on, with a JDK 17 or newer for Gradle. The Kotlin/Native toolchain downloads itself.
  • Kotlin 2.3 or newer; the samples use 2.4.21, the version kcoap is built with.
  • An x86-64 gateway to run on. The executable needs no JVM and no system OpenSSL.

Install status

On Maven Central

kcoap 0.1.0 is on Maven Central, its linuxX64 artifacts included. CI runs every common test as native Linux code, and the WebSocket loopback test natively; the UDP and TCP adapter tests run on the JVM only, from the same common code.

Set up

  1. Create the build file

    The bill of materials, kcoap-bom, sets one version for every kcoap module, so the modules name none.

    Kotlin DSL

    build.gradle.kts

    plugins {
        kotlin("multiplatform") version "2.4.21"
    }
    
    repositories {
        mavenCentral()
    }
    
    kotlin {
        linuxX64 {
            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")
                implementation("dev.kcoap:kcoap-crypto-default")
                implementation("dev.kcoap:kcoap-oscore")
                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 = { module = "dev.kcoap:kcoap-transport-ktor" }
    kcoap-crypto-default = { module = "dev.kcoap:kcoap-crypto-default" }
    kcoap-oscore = { module = "dev.kcoap:kcoap-oscore" }
    kcoap-edhoc-oscore = { module = "dev.kcoap:kcoap-edhoc-oscore" }
    
    [bundles]
    kcoap = [
        "kcoap-coap",
        "kcoap-transport-ktor",
        "kcoap-crypto-default",
        "kcoap-oscore",
        "kcoap-edhoc-oscore",
    ]
    
    [plugins]
    kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }

    build.gradle.kts

    plugins {
        alias(libs.plugins.kotlin.multiplatform)
    }
    
    repositories {
        mavenCentral()
    }
    
    kotlin {
        linuxX64 {
            binaries.executable()
        }
        sourceSets {
            commonMain.dependencies {
                implementation(project.dependencies.platform(libs.kcoap.bom))
                implementation(libs.bundles.kcoap)
            }
        }
    }

    A standard Kotlin Multiplatform build file; kcoap’s coordinates are checked. kcoap’s repository has no Linux application that builds this file.

First client and server

The same server and client as in the JVM guide, as a native program. On Kotlin/Native, Dispatchers.Default runs the coroutines.

src/linuxX64Main/kotlin/Main.kt

import dev.kcoap.coap.CoapResponse
import dev.kcoap.coap.ContentFormat
import dev.kcoap.coap.client.CoapClient
import dev.kcoap.coap.server.CoapServer
import dev.kcoap.transport.ktor.KtorUdpTransport
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.cancel
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val scope = CoroutineScope(Dispatchers.Default + SupervisorJob())
    try {
        var stored = "nothing yet"
        val transport = KtorUdpTransport.bind("127.0.0.1", 5683)
        val server = CoapServer(transport, scope) {
            resource("hello") { get { CoapResponse.content("Hello, $peer") } }
            resource("store") {
                get { CoapResponse.content(stored) }
                put {
                    stored = payloadAsText()
                    CoapResponse.changed()
                }
            }
        }

        val client = CoapClient(KtorUdpTransport.bind("127.0.0.1"), scope)
        val uri = "coap://127.0.0.1:5683"
        println(client.get("$uri/hello").payloadAsText())
        val body = "on".encodeToByteArray()
        client.put("$uri/store", body, ContentFormat.TEXT_PLAIN)
        println(client.get("$uri/store").payloadAsText())

        client.close()
        server.close()
    } finally {
        scope.cancel()
    }
}

The kcoap lines are the guide’s, which CI compiles and runs on the JVM; the same common code runs natively in CI’s Linux tests. This program as a whole is not compiled in CI.

Build the executable and run it:

Terminal

./gradlew linkReleaseExecutableLinuxX64
# the .kexe file to copy to the gateway
ls build/bin/linuxX64/releaseExecutable/

A gateway that serves browsers adds the WebSocket listener: kcoap-transport-ktor-websocket-server with io.ktor:ktor-server-cio:3.6.1, whose CIO engine runs natively on Linux. The TCP and WebSocket example is the same code.

Keys and state on a gateway

  • Pre-shared OSCORE keys need a durable SequenceNumberStore. The Linux recipe uses POSIX calls with fsync on the file and its directory. It is not compiled or tested on Linux yet.
  • EDHOC derives new keys for each session and needs no durable store. Bound the security contexts on a long-running gateway: InMemoryContextRepository never evicts.
  • No post-quantum EDHOC on Linux native yet: ML-KEM and ML-DSA come only from kcoap-crypto-bc, which is for the JVM and Android.

Platform notes

OpenSSL

DefaultCryptoBackend() uses cryptography-kotlin’s prebuilt OpenSSL 3 provider, linked into the executable. Updates of that OpenSSL come with kcoap’s cryptography-kotlin version.

ARM gateways

There is no linuxArm64 target yet; it is planned. On an ARM gateway with a Java 17 runtime, the JVM artifacts are today’s route. No ARM machine runs in CI.

TLS

There is no TLS on Linux native: ktor has none there, so neither a coaps+tcp client nor coaps+ws runs on the gateway. Terminate TLS in a proxy in front of it, such as stunnel or nginx’s stream module, as ADR 0010 recommends for native gateways. DTLS for coaps:// comes last.

Troubleshooting

Could not find dev.kcoap:…-linuxx64
Check that mavenCentral() is in your repositories, and that the target is linuxX64: kcoap publishes no other Linux target.
Dispatchers.IO does not resolve
On Kotlin/Native it needs import kotlinx.coroutines.IO. Dispatchers.Default works without it.
Cannot resolve '…': configure an EndpointResolver
The default resolver knows no DNS for coap://. Use an IP address, or set a resolver in CoapClientConfig.
The program will not start on an ARM board
The executable is x86-64 only. Use the JVM artifacts on a Java 17 runtime there.

Next steps