
CoAP, OSCORE and EDHOC implementation with byte-for-byte RFC test vectors, live interop testing, Q-Block support, post-quantum EDHOC and fail-closed message security.
CoAP, OSCORE and EDHOC for Kotlin Multiplatform
Website · Getting started · Documentation · Guide · Platforms · RFC compliance · Contributing · Sponsor
kcoap™ implements CoAP, OSCORE and EDHOC once, in common Kotlin, for Android, iOS, JVM servers, Linux gateways, browsers and Node.js. It aims at complete compliance with the published RFCs and checks its parts against the RFCs' own test vectors where they exist and in live interop with libcoap, whose maintainers include RFC authors, and libedhoc. 0.1.0 is its first release (project status).
0.x: the API may still change. Until 1.0, a minor release may break the API; every breaking change is in the changelog with a migration note, and versioning says what each kind of release promises.
CryptoBackend, so keys can live in a secure element, and
transports, credential resolution, EAD, logging sinks and interceptors are interfaces with defaults
(architecture).States follow the checklist, which names every open item and its next step; RFC compliance has the detail section by section.
| Protocol | RFC | State | Verified by |
|---|---|---|---|
| CoAP over UDP: messaging, client and server, options, URIs, conditional requests | 7252 | partial: caching (§5.6), proxying (§5.7) and multicast (§8) to do; option-length checks (§5.4.3) and dot-segment removal in URIs (§5.10.1) open; DTLS (§9) last | per-section unit tests and end-to-end runs on a simulated lossy network; libcoap both directions |
Link format, /.well-known/core
|
6690 | done | RFC 6690 §5 examples; libcoap discovery both directions |
| Observe | 7641 | partial: the Content-Format of notifications and 4.06 (§4.2) to do |
ObserveTest; libcoap over UDP, TCP and WebSockets |
| Block-wise transfers | 7959 | partial: inner Block-wise only; If-None-Match is repeated after the first Block1 block (§2.10) |
BlockwiseTest; libcoap both directions |
| Q-Block | 9177 | done, off by default; §4.8 (multicast) and §8–9 (proxies) not applicable | every figure of §10 and Appendices A–B on virtual time; soaks at 10 % and 30 % loss; libcoap 4.3.5b both directions over UDP, TCP and WebSockets |
| FETCH, PATCH, iPATCH | 8132 | partial: the FETCH body is not part of the observation and Block2 keys |
RequestResponseTest, ObserveTest
|
| No-Response | 7967 | partial: the server is done; the client still waits for its timeout |
RequestResponseTest, EdgeCaseTest
|
| Echo, Request-Tag | 9175 | partial: address verification against amplification done; server freshness checks (§2.3) to do |
MessageSecurityTest, BlockwiseTest, AmplificationTest; libcoap |
| Hop-Limit | 8768 | partial: the option and 5.08 exist; the processing belongs to proxies, which kcoap does not have yet | CoapModelTest |
| CoAP over TCP and WebSockets: CSM, Ping/Pong, Release, Abort, BERT, Observe | 8323 | partial: TLS as a client only, coaps+tcp on the JVM without ALPN and coaps+ws on the ktor engine's TLS where it authenticates the server (by default Apple and browsers; on the JVM with an application's HttpClient), both cross-tested; no TLS listener (platforms) |
RFC 8323 figures byte for byte; in-memory and loopback tests; libcoap both directions over TCP and WebSockets |
| OSCORE | 8613 | partial: Outer Block-wise, protected signaling over TCP, proxies, HTTP and Appendix B.2 to do; nonce reuse after sequence-number exhaustion (§7.2.1) open | every Appendix C vector byte for byte; libcoap both directions, raw and through the stack |
| EDHOC: methods 0–3, suites 0–6 and 24 | 9528 | partial: suite 25, CWT and C509 credentials, and the Initiator's C_R = C_I check to do | both RFC 9529 traces byte for byte, all §4 invalid messages; libedhoc both roles |
| Post-quantum EDHOC: KEM-based key exchange (private suite -24) | draft-ietf-lake-pqsuites §3 | done (JVM, Android) | round trips with real ML-KEM and ML-DSA; libedhoc (liboqs) both roles |
| EDHOC over CoAP, EDHOC→OSCORE, combined request | 9528 App. A, 9668 | partial: forward flow and combined request work end to end, with MUSTs still missing (the client's EDHOC error on a failed message_2 or message_4, the sequential fallback for a large COMB_PAYLOAD, Outer Block1 reassembly); reverse flow (App. A.2.2) to do; no independent peer yet | RFC 9668 Figure 4 byte for byte; full-stack tests |
| ML-KEM, ML-DSA | FIPS 203, 204 | done (JVM, Android) | NIST ACVP vectors |
| DTLS 1.2 | 6347, 7925, 9146 | interfaces only; the engine comes last | — |
kcoap is on Maven Central: dev.kcoap:<module>:<version>, under the verified dev.kcoap namespace. In
your build, import the bill of materials kcoap-bom, which gives every kcoap module the same version, and
name the modules without one:
// build.gradle.kts
repositories {
mavenCentral()
}
dependencies {
implementation(platform("dev.kcoap:kcoap-bom:0.1.0"))
implementation("dev.kcoap:kcoap-coap") // CoAP client and server
implementation("dev.kcoap:kcoap-transport-ktor") // UDP and TCP sockets
implementation("dev.kcoap:kcoap-crypto-default") // the platform's cryptography
implementation("dev.kcoap:kcoap-oscore") // OSCORE
implementation("dev.kcoap:kcoap-edhoc-oscore") // EDHOC over CoAP, into OSCORE
}Getting started says which modules each use case needs (client, server, OSCORE,
EDHOC, post-quantum, each transport and each platform), how to add them in a Kotlin Multiplatform or Maven
build, and walks through a first client and server, OSCORE and EDHOC, which
samples/jvm-consumer runs as an application of its own. In a Kotlin
Multiplatform project the adapters a target lacks go into the source sets of the targets that have them:
kcoap-transport-ktor builds for the JVM, Apple and Linux, and browsers use kcoap-transport-ktor-websocket
instead (platforms).
An OSCORE server and a client that talks to it:
// Resources take OSCORE requests only, unless they say otherwise.
val contexts = InMemoryContextRepository().apply { add(serverContext) }
val server = CoapServer(
KtorUdpTransport.bind("0.0.0.0", 5683),
scope,
CoapServerConfig(security = OscoreServer(contexts)),
) {
resource("lights") {
get { CoapResponse.content("on for ${securityIdentity?.description}") }
}
resource("status") {
access = AccessPolicy.Public // for anyone, with or without OSCORE
get { CoapResponse.content("up") }
}
}
val client = CoapClient(
KtorUdpTransport.bind(),
scope,
CoapClientConfig { security = OscoreClient(clientContext) },
)
println(client.get("coap://192.0.2.1/lights").payloadAsText())With EDHOC instead of pre-shared OSCORE keys, the client runs the handshake first and its first OSCORE request carries EDHOC message_3 (RFC 9668), two round trips in all:
val security = PeerSecurity()
val client = CoapClient(KtorUdpTransport.bind(), scope, CoapClientConfig { this.security = security })
val server = CoapUri.parse("coap://192.0.2.1")
val (session, protection) =
EdhocClientHandshake.over(client, server, initiatorConfig, crypto).runCombined()
security.install(client, server, protection)
client.get("coap://192.0.2.1/lights")Message security fails closed (ADR 0008):
AccessPolicy (Public, MessageSecurityRequired, Authenticated, or
your own on the request's identities), inherited down the tree; with security set, the default is
MessageSecurityRequired. A refused request gets 4.01 before any handler, block-wise buffer, observation
or burst, and /.well-known/core lists only what the caller may use.CoapException(UNVERIFIED_RESPONSE), which carries it. A request without a context or installed
protection fails with CoapException(SECURITY) instead of going out in plaintext, unless
allowUnprotected says otherwise.The EDHOC server mounts EdhocResource (public of its own) under /.well-known and uses
CombinedRequestServer around its OscoreServer; the EdhocServer behind both adds a context per
handshake to a MutableSecurityContextRepository, which a production server bounds. Its handlers and
policies see an EdhocIdentity with the client's authenticated credential. See
kcoap-edhoc-oscore.
More in the client and server guide.
| Module | What it is |
|---|---|
kcoap-bom |
The bill of materials: one version for every published module, for Gradle and Maven builds |
kcoap-common |
Logging API and sinks, hex, constant-time helpers, KcoapException, the opt-in markers @InternalKcoapApi and @ExperimentalKcoapApi
|
kcoap-crypto |
The CryptoBackend SPI (all suspend, opaque key handles), AES-CCM, HKDF, SHAKE256, KMAC256, SEC1 points, ECDSA DER, X.509 parsing |
kcoap-crypto-default |
Backend on cryptography-kotlin: JCA on JVM/Android, CryptoKit and CommonCrypto on Apple, OpenSSL on Linux, WebCrypto in browsers and Node.js |
kcoap-crypto-bc |
Post-quantum backend on Bouncy Castle: ML-KEM and ML-DSA (JVM, Android) |
kcoap-crypto-testsuite |
Conformance suite for crypto backends, for test source sets: the supports contract, NIST's ACVP ML-KEM and ML-DSA vectors, a capability report per target |
kcoap-cbor |
Deterministic CBOR and CBOR sequences |
kcoap-cose |
COSE structures, COSE_Key, CWT Claims Sets |
kcoap-transport |
Transport interfaces, endpoints, peer identities, URI schemes |
kcoap-transport-ktor |
UDP and TCP on ktor-network (JVM, Apple, Linux; not the web), and a coaps+tcp TLS client on the JVM |
kcoap-transport-ktor-websocket |
WebSocket client on the ktor client, any engine, browsers included |
kcoap-transport-ktor-websocket-server |
WebSocket server on the ktor server, standalone or mounted |
kcoap-testkit |
Simulated network with loss, duplication and reordering, and in-memory TCP/WebSocket connections, for tests |
kcoap-coap-message |
CoAP messages, options, URIs, link format, the UDP and RFC 8323 codecs, the message-security SPI; no coroutines |
kcoap-coap |
The CoAP endpoint, CoapClient, CoapServer, on kcoap-coap-message, which it brings along |
kcoap-oscore |
OSCORE; it needs kcoap-coap-message, not the endpoint |
kcoap-edhoc |
EDHOC Initiator and Responder |
kcoap-edhoc-oscore |
EDHOC over CoAP, EDHOC→OSCORE, the combined request |
kcoap-dtls |
DTLS interfaces and registries; the engine is implemented last, and the module is not published until then |
Core modules (protocol, wire and SPI code) are common Kotlin only, which the build checks. Every
published module has its public API committed as ABI dumps in <module>/api, so API changes are
reviewed as such; declarations marked @InternalKcoapApi are plumbing between kcoap's modules, not API
(code style, versioning).
Everything is common Kotlin; the platforms differ only in what their cryptography offers, which the
crypto backend reports through capability checks (crypto.supports(algorithm),
CipherSuite.isSupportedBy(crypto, method); ADR 0001) and fills
with common-code fallbacks where they are small and safe. EDHOC offers and accepts only the suites the
backend runs. Only adapters that wrap a runtime-bound library build for fewer targets.
| Target | Runtime | Crypto under DefaultCryptoBackend
|
Modules |
|---|---|---|---|
jvm |
JVM servers, Android 8.0 and later (minSdk 26) | JCA | all |
iosArm64, iosSimulatorArm64, macosArm64
|
Apple | CryptoKit, CommonCrypto | all but kcoap-crypto-bc
|
linuxX64 |
Linux gateways | OpenSSL 3 | all but kcoap-crypto-bc
|
js, wasmJs
|
browsers, Node.js | WebCrypto | all but kcoap-crypto-bc, kcoap-transport-ktor and kcoap-transport-ktor-websocket-server
|
Platforms has the minimum versions, the algorithms and EDHOC suites each target runs (from the conformance suite's capability report), the TLS each runtime has, client and server, and what mobile apps must handle when they are suspended or change networks.
CoAP messages and codecs (UDP and RFC 8323 framing), OSCORE, EDHOC (suites 0–3, 6 and 24) and the
EDHOC→OSCORE glue run in a browser, and so does the client and server stack, over a DatagramTransport
the application supplies (as kcoap-testkit's in-memory network does in the tests) and over WebSockets
(RFC 8323) with kcoap-transport-ktor-websocket, whose js tests also run in a headless browser against
a JVM listener (Firefox so far; a CI job in Chrome). Browsers have no UDP, so reaching a device takes the
WebSocket transport and a proxy such as libcoap's coap-server; OSCORE and EDHOC stay end to end across
it. samples/js-consumer is a page that reads a resource with OSCORE over
coap+ws, built as a production webpack bundle of about 1.1 MB minified (310 KB with gzip) under a size budget
the build checks, and run in headless Chrome in CI (platforms). What WebCrypto
lacks:
UnsupportedAlgorithmException, so EDHOC suites 4 and 5 are neither offered nor
accepted there.UnsupportedAlgorithmException; ask supports(...) before offering them.Details in Architecture: browsers and kcoap-crypto-default.
The app uses the jvm artifacts, from API level 26 (Android 8.0) on. Checks hold that line:
checkAndroidApi, part of check and scripts/test unit, runs animal-sniffer over every module's jvm
jar against the API 26 signature without the Android SDK, checkAndroidApiDependencies does the same for
the libraries behind them and fails on any use not yet triaged, and CI builds
samples/android-consumer, an app at minSdk 26 that uses kcoap from
Maven, with R8 on its release builds and lint. Apps need no R8 rules of their own and no core library
desugaring; the sample's README lists what an app needs (Kotlin 2.3 or newer, Java 17 bytecode) and what
the check found in ktor, cryptography-kotlin and Bouncy Castle. Not yet run on an emulator or device;
that is planned (Q-Block and platforms plan).
The documentation hub lists every guide, design record and reference page. To start:
| Read | For |
|---|---|
| Getting started | which modules to add for each use case, a first client and server, OSCORE, EDHOC, post-quantum |
| Client and server guide | serving and requesting resources over UDP, TCP and WebSockets, Q-Block, message security |
| Platforms | minimum versions, algorithms and EDHOC suites per target, TLS per runtime, mobile lifecycle |
| Architecture | layers, transports, security layering, extension points |
| RFC compliance and interop | what is implemented, section by section, and how it is cross-tested |
| API reference | every public declaration (Dokka), published by each release; ./gradlew dokkaGenerate builds it into build/dokka/html
|
Needs a JDK 17 or newer; Gradle downloads everything else, Node.js for the web tests included. Each test suite is one command:
scripts/test unit # unit tests on every target this machine builds, then the build checks
scripts/test interop # libcoap and libedhoc cross-tests in both roles; builds Docker images
scripts/test coverage # unit and interop tests with the coverage report and the 90% floor
scripts/test apple # the common tests against CryptoKit and CommonCrypto (macOS only)
scripts/test swift # the Swift smoke test against the KcoapSmoke framework (macOS only)
scripts/test all # unit, interop and coverageExtra arguments go to Gradle (scripts/test interop --tests '*Oscore*'), and every run ends with a
table of tests per target. CI runs the same suites on Linux and macOS for every push to main and every
pull request; a v* tag publishes a release (releasing). Details, including what
each suite covers, are in testing.
Test vectors are generated from the RFC texts and NIST files by tools/regen-vectors.sh and
tools/regen-pq-vectors.sh.
kcoap 0.1.0, its first release, came out on 2026-11-06 and is on Maven Central. main holds it and what merges
after it; the next version is 0.2.0. The website is kcoap.dev, and the
API reference is on GitHub Pages.
coaps://; OSCORE and EDHOC protect messages end to
end over any transport.Contributions are welcome. kcoap uses the Developer Certificate of Origin instead of a CLA: sign
off every commit with git commit -s, which adds a Signed-off-by line matching the commit's author,
and a check on every pull request verifies it. Contributions are licensed under Apache-2.0 and you keep
your copyright. CONTRIBUTING.md has the workflow, and the
Code of Conduct applies to everyone who takes part. The
code style and testing pages say how the code is written and
tested.
Do not report vulnerabilities in public issues. SECURITY.md says how to report them privately and what to expect.
Questions, bug reports and feature requests go to GitHub Issues; SUPPORT.md says what to include and what to expect from a project with one maintainer.
kcoap has no sponsors yet. Sponsorship through GitHub Sponsors or Open Collective is planned, and SPONSORS.md says what it pays for. Sponsors will be listed in SPONSORS.md, in this section and at kcoap.dev/sponsors.
kcoap is licensed under the Apache License 2.0; see also NOTICE and the third-party material.
Copyright 2026 Adrian Sołtys and the kcoap contributors.
kcoap™ and kcoap.dev™ are trademarks of Adrian Sołtys. The license grants no permission to use them beyond describing the origin of the work (Apache-2.0, section 6); TRADEMARKS.md says how the names may be used.
CoAP, OSCORE and EDHOC for Kotlin Multiplatform
Website · Getting started · Documentation · Guide · Platforms · RFC compliance · Contributing · Sponsor
kcoap™ implements CoAP, OSCORE and EDHOC once, in common Kotlin, for Android, iOS, JVM servers, Linux gateways, browsers and Node.js. It aims at complete compliance with the published RFCs and checks its parts against the RFCs' own test vectors where they exist and in live interop with libcoap, whose maintainers include RFC authors, and libedhoc. 0.1.0 is its first release (project status).
0.x: the API may still change. Until 1.0, a minor release may break the API; every breaking change is in the changelog with a migration note, and versioning says what each kind of release promises.
CryptoBackend, so keys can live in a secure element, and
transports, credential resolution, EAD, logging sinks and interceptors are interfaces with defaults
(architecture).States follow the checklist, which names every open item and its next step; RFC compliance has the detail section by section.
| Protocol | RFC | State | Verified by |
|---|---|---|---|
| CoAP over UDP: messaging, client and server, options, URIs, conditional requests | 7252 | partial: caching (§5.6), proxying (§5.7) and multicast (§8) to do; option-length checks (§5.4.3) and dot-segment removal in URIs (§5.10.1) open; DTLS (§9) last | per-section unit tests and end-to-end runs on a simulated lossy network; libcoap both directions |
Link format, /.well-known/core
|
6690 | done | RFC 6690 §5 examples; libcoap discovery both directions |
| Observe | 7641 | partial: the Content-Format of notifications and 4.06 (§4.2) to do |
ObserveTest; libcoap over UDP, TCP and WebSockets |
| Block-wise transfers | 7959 | partial: inner Block-wise only; If-None-Match is repeated after the first Block1 block (§2.10) |
BlockwiseTest; libcoap both directions |
| Q-Block | 9177 | done, off by default; §4.8 (multicast) and §8–9 (proxies) not applicable | every figure of §10 and Appendices A–B on virtual time; soaks at 10 % and 30 % loss; libcoap 4.3.5b both directions over UDP, TCP and WebSockets |
| FETCH, PATCH, iPATCH | 8132 | partial: the FETCH body is not part of the observation and Block2 keys |
RequestResponseTest, ObserveTest
|
| No-Response | 7967 | partial: the server is done; the client still waits for its timeout |
RequestResponseTest, EdgeCaseTest
|
| Echo, Request-Tag | 9175 | partial: address verification against amplification done; server freshness checks (§2.3) to do |
MessageSecurityTest, BlockwiseTest, AmplificationTest; libcoap |
| Hop-Limit | 8768 | partial: the option and 5.08 exist; the processing belongs to proxies, which kcoap does not have yet | CoapModelTest |
| CoAP over TCP and WebSockets: CSM, Ping/Pong, Release, Abort, BERT, Observe | 8323 | partial: TLS as a client only, coaps+tcp on the JVM without ALPN and coaps+ws on the ktor engine's TLS where it authenticates the server (by default Apple and browsers; on the JVM with an application's HttpClient), both cross-tested; no TLS listener (platforms) |
RFC 8323 figures byte for byte; in-memory and loopback tests; libcoap both directions over TCP and WebSockets |
| OSCORE | 8613 | partial: Outer Block-wise, protected signaling over TCP, proxies, HTTP and Appendix B.2 to do; nonce reuse after sequence-number exhaustion (§7.2.1) open | every Appendix C vector byte for byte; libcoap both directions, raw and through the stack |
| EDHOC: methods 0–3, suites 0–6 and 24 | 9528 | partial: suite 25, CWT and C509 credentials, and the Initiator's C_R = C_I check to do | both RFC 9529 traces byte for byte, all §4 invalid messages; libedhoc both roles |
| Post-quantum EDHOC: KEM-based key exchange (private suite -24) | draft-ietf-lake-pqsuites §3 | done (JVM, Android) | round trips with real ML-KEM and ML-DSA; libedhoc (liboqs) both roles |
| EDHOC over CoAP, EDHOC→OSCORE, combined request | 9528 App. A, 9668 | partial: forward flow and combined request work end to end, with MUSTs still missing (the client's EDHOC error on a failed message_2 or message_4, the sequential fallback for a large COMB_PAYLOAD, Outer Block1 reassembly); reverse flow (App. A.2.2) to do; no independent peer yet | RFC 9668 Figure 4 byte for byte; full-stack tests |
| ML-KEM, ML-DSA | FIPS 203, 204 | done (JVM, Android) | NIST ACVP vectors |
| DTLS 1.2 | 6347, 7925, 9146 | interfaces only; the engine comes last | — |
kcoap is on Maven Central: dev.kcoap:<module>:<version>, under the verified dev.kcoap namespace. In
your build, import the bill of materials kcoap-bom, which gives every kcoap module the same version, and
name the modules without one:
// build.gradle.kts
repositories {
mavenCentral()
}
dependencies {
implementation(platform("dev.kcoap:kcoap-bom:0.1.0"))
implementation("dev.kcoap:kcoap-coap") // CoAP client and server
implementation("dev.kcoap:kcoap-transport-ktor") // UDP and TCP sockets
implementation("dev.kcoap:kcoap-crypto-default") // the platform's cryptography
implementation("dev.kcoap:kcoap-oscore") // OSCORE
implementation("dev.kcoap:kcoap-edhoc-oscore") // EDHOC over CoAP, into OSCORE
}Getting started says which modules each use case needs (client, server, OSCORE,
EDHOC, post-quantum, each transport and each platform), how to add them in a Kotlin Multiplatform or Maven
build, and walks through a first client and server, OSCORE and EDHOC, which
samples/jvm-consumer runs as an application of its own. In a Kotlin
Multiplatform project the adapters a target lacks go into the source sets of the targets that have them:
kcoap-transport-ktor builds for the JVM, Apple and Linux, and browsers use kcoap-transport-ktor-websocket
instead (platforms).
An OSCORE server and a client that talks to it:
// Resources take OSCORE requests only, unless they say otherwise.
val contexts = InMemoryContextRepository().apply { add(serverContext) }
val server = CoapServer(
KtorUdpTransport.bind("0.0.0.0", 5683),
scope,
CoapServerConfig(security = OscoreServer(contexts)),
) {
resource("lights") {
get { CoapResponse.content("on for ${securityIdentity?.description}") }
}
resource("status") {
access = AccessPolicy.Public // for anyone, with or without OSCORE
get { CoapResponse.content("up") }
}
}
val client = CoapClient(
KtorUdpTransport.bind(),
scope,
CoapClientConfig { security = OscoreClient(clientContext) },
)
println(client.get("coap://192.0.2.1/lights").payloadAsText())With EDHOC instead of pre-shared OSCORE keys, the client runs the handshake first and its first OSCORE request carries EDHOC message_3 (RFC 9668), two round trips in all:
val security = PeerSecurity()
val client = CoapClient(KtorUdpTransport.bind(), scope, CoapClientConfig { this.security = security })
val server = CoapUri.parse("coap://192.0.2.1")
val (session, protection) =
EdhocClientHandshake.over(client, server, initiatorConfig, crypto).runCombined()
security.install(client, server, protection)
client.get("coap://192.0.2.1/lights")Message security fails closed (ADR 0008):
AccessPolicy (Public, MessageSecurityRequired, Authenticated, or
your own on the request's identities), inherited down the tree; with security set, the default is
MessageSecurityRequired. A refused request gets 4.01 before any handler, block-wise buffer, observation
or burst, and /.well-known/core lists only what the caller may use.CoapException(UNVERIFIED_RESPONSE), which carries it. A request without a context or installed
protection fails with CoapException(SECURITY) instead of going out in plaintext, unless
allowUnprotected says otherwise.The EDHOC server mounts EdhocResource (public of its own) under /.well-known and uses
CombinedRequestServer around its OscoreServer; the EdhocServer behind both adds a context per
handshake to a MutableSecurityContextRepository, which a production server bounds. Its handlers and
policies see an EdhocIdentity with the client's authenticated credential. See
kcoap-edhoc-oscore.
More in the client and server guide.
| Module | What it is |
|---|---|
kcoap-bom |
The bill of materials: one version for every published module, for Gradle and Maven builds |
kcoap-common |
Logging API and sinks, hex, constant-time helpers, KcoapException, the opt-in markers @InternalKcoapApi and @ExperimentalKcoapApi
|
kcoap-crypto |
The CryptoBackend SPI (all suspend, opaque key handles), AES-CCM, HKDF, SHAKE256, KMAC256, SEC1 points, ECDSA DER, X.509 parsing |
kcoap-crypto-default |
Backend on cryptography-kotlin: JCA on JVM/Android, CryptoKit and CommonCrypto on Apple, OpenSSL on Linux, WebCrypto in browsers and Node.js |
kcoap-crypto-bc |
Post-quantum backend on Bouncy Castle: ML-KEM and ML-DSA (JVM, Android) |
kcoap-crypto-testsuite |
Conformance suite for crypto backends, for test source sets: the supports contract, NIST's ACVP ML-KEM and ML-DSA vectors, a capability report per target |
kcoap-cbor |
Deterministic CBOR and CBOR sequences |
kcoap-cose |
COSE structures, COSE_Key, CWT Claims Sets |
kcoap-transport |
Transport interfaces, endpoints, peer identities, URI schemes |
kcoap-transport-ktor |
UDP and TCP on ktor-network (JVM, Apple, Linux; not the web), and a coaps+tcp TLS client on the JVM |
kcoap-transport-ktor-websocket |
WebSocket client on the ktor client, any engine, browsers included |
kcoap-transport-ktor-websocket-server |
WebSocket server on the ktor server, standalone or mounted |
kcoap-testkit |
Simulated network with loss, duplication and reordering, and in-memory TCP/WebSocket connections, for tests |
kcoap-coap-message |
CoAP messages, options, URIs, link format, the UDP and RFC 8323 codecs, the message-security SPI; no coroutines |
kcoap-coap |
The CoAP endpoint, CoapClient, CoapServer, on kcoap-coap-message, which it brings along |
kcoap-oscore |
OSCORE; it needs kcoap-coap-message, not the endpoint |
kcoap-edhoc |
EDHOC Initiator and Responder |
kcoap-edhoc-oscore |
EDHOC over CoAP, EDHOC→OSCORE, the combined request |
kcoap-dtls |
DTLS interfaces and registries; the engine is implemented last, and the module is not published until then |
Core modules (protocol, wire and SPI code) are common Kotlin only, which the build checks. Every
published module has its public API committed as ABI dumps in <module>/api, so API changes are
reviewed as such; declarations marked @InternalKcoapApi are plumbing between kcoap's modules, not API
(code style, versioning).
Everything is common Kotlin; the platforms differ only in what their cryptography offers, which the
crypto backend reports through capability checks (crypto.supports(algorithm),
CipherSuite.isSupportedBy(crypto, method); ADR 0001) and fills
with common-code fallbacks where they are small and safe. EDHOC offers and accepts only the suites the
backend runs. Only adapters that wrap a runtime-bound library build for fewer targets.
| Target | Runtime | Crypto under DefaultCryptoBackend
|
Modules |
|---|---|---|---|
jvm |
JVM servers, Android 8.0 and later (minSdk 26) | JCA | all |
iosArm64, iosSimulatorArm64, macosArm64
|
Apple | CryptoKit, CommonCrypto | all but kcoap-crypto-bc
|
linuxX64 |
Linux gateways | OpenSSL 3 | all but kcoap-crypto-bc
|
js, wasmJs
|
browsers, Node.js | WebCrypto | all but kcoap-crypto-bc, kcoap-transport-ktor and kcoap-transport-ktor-websocket-server
|
Platforms has the minimum versions, the algorithms and EDHOC suites each target runs (from the conformance suite's capability report), the TLS each runtime has, client and server, and what mobile apps must handle when they are suspended or change networks.
CoAP messages and codecs (UDP and RFC 8323 framing), OSCORE, EDHOC (suites 0–3, 6 and 24) and the
EDHOC→OSCORE glue run in a browser, and so does the client and server stack, over a DatagramTransport
the application supplies (as kcoap-testkit's in-memory network does in the tests) and over WebSockets
(RFC 8323) with kcoap-transport-ktor-websocket, whose js tests also run in a headless browser against
a JVM listener (Firefox so far; a CI job in Chrome). Browsers have no UDP, so reaching a device takes the
WebSocket transport and a proxy such as libcoap's coap-server; OSCORE and EDHOC stay end to end across
it. samples/js-consumer is a page that reads a resource with OSCORE over
coap+ws, built as a production webpack bundle of about 1.1 MB minified (310 KB with gzip) under a size budget
the build checks, and run in headless Chrome in CI (platforms). What WebCrypto
lacks:
UnsupportedAlgorithmException, so EDHOC suites 4 and 5 are neither offered nor
accepted there.UnsupportedAlgorithmException; ask supports(...) before offering them.Details in Architecture: browsers and kcoap-crypto-default.
The app uses the jvm artifacts, from API level 26 (Android 8.0) on. Checks hold that line:
checkAndroidApi, part of check and scripts/test unit, runs animal-sniffer over every module's jvm
jar against the API 26 signature without the Android SDK, checkAndroidApiDependencies does the same for
the libraries behind them and fails on any use not yet triaged, and CI builds
samples/android-consumer, an app at minSdk 26 that uses kcoap from
Maven, with R8 on its release builds and lint. Apps need no R8 rules of their own and no core library
desugaring; the sample's README lists what an app needs (Kotlin 2.3 or newer, Java 17 bytecode) and what
the check found in ktor, cryptography-kotlin and Bouncy Castle. Not yet run on an emulator or device;
that is planned (Q-Block and platforms plan).
The documentation hub lists every guide, design record and reference page. To start:
| Read | For |
|---|---|
| Getting started | which modules to add for each use case, a first client and server, OSCORE, EDHOC, post-quantum |
| Client and server guide | serving and requesting resources over UDP, TCP and WebSockets, Q-Block, message security |
| Platforms | minimum versions, algorithms and EDHOC suites per target, TLS per runtime, mobile lifecycle |
| Architecture | layers, transports, security layering, extension points |
| RFC compliance and interop | what is implemented, section by section, and how it is cross-tested |
| API reference | every public declaration (Dokka), published by each release; ./gradlew dokkaGenerate builds it into build/dokka/html
|
Needs a JDK 17 or newer; Gradle downloads everything else, Node.js for the web tests included. Each test suite is one command:
scripts/test unit # unit tests on every target this machine builds, then the build checks
scripts/test interop # libcoap and libedhoc cross-tests in both roles; builds Docker images
scripts/test coverage # unit and interop tests with the coverage report and the 90% floor
scripts/test apple # the common tests against CryptoKit and CommonCrypto (macOS only)
scripts/test swift # the Swift smoke test against the KcoapSmoke framework (macOS only)
scripts/test all # unit, interop and coverageExtra arguments go to Gradle (scripts/test interop --tests '*Oscore*'), and every run ends with a
table of tests per target. CI runs the same suites on Linux and macOS for every push to main and every
pull request; a v* tag publishes a release (releasing). Details, including what
each suite covers, are in testing.
Test vectors are generated from the RFC texts and NIST files by tools/regen-vectors.sh and
tools/regen-pq-vectors.sh.
kcoap 0.1.0, its first release, came out on 2026-11-06 and is on Maven Central. main holds it and what merges
after it; the next version is 0.2.0. The website is kcoap.dev, and the
API reference is on GitHub Pages.
coaps://; OSCORE and EDHOC protect messages end to
end over any transport.Contributions are welcome. kcoap uses the Developer Certificate of Origin instead of a CLA: sign
off every commit with git commit -s, which adds a Signed-off-by line matching the commit's author,
and a check on every pull request verifies it. Contributions are licensed under Apache-2.0 and you keep
your copyright. CONTRIBUTING.md has the workflow, and the
Code of Conduct applies to everyone who takes part. The
code style and testing pages say how the code is written and
tested.
Do not report vulnerabilities in public issues. SECURITY.md says how to report them privately and what to expect.
Questions, bug reports and feature requests go to GitHub Issues; SUPPORT.md says what to include and what to expect from a project with one maintainer.
kcoap has no sponsors yet. Sponsorship through GitHub Sponsors or Open Collective is planned, and SPONSORS.md says what it pays for. Sponsors will be listed in SPONSORS.md, in this section and at kcoap.dev/sponsors.
kcoap is licensed under the Apache License 2.0; see also NOTICE and the third-party material.
Copyright 2026 Adrian Sołtys and the kcoap contributors.
kcoap™ and kcoap.dev™ are trademarks of Adrian Sołtys. The license grants no permission to use them beyond describing the origin of the work (Apache-2.0, section 6); TRADEMARKS.md says how the names may be used.