ABI dumps
Every published module has committed JVM and klib API dumps. checkKotlinAbi fails on any change to them that is not committed with the code.
Features
Each feature below names the tests that back it and what is still open. The states follow the project’s checklist, which lists every requirement with its evidence and next step.
Conformance
Where a specification prints test vectors, kcoap replays them and compares every intermediate value, not only the result.
Rfc8613VectorsTest, Rfc9529TraceTest, Rfc9529InvalidTracesTest, QBlockFiguresTest, AesCcmTest, MlKemKnownAnswerTest, MlDsaKnownAnswerTest.Vectors come from RFC 8613 Appendix C, the RFC 9529 traces 1 and 2 and NIST's ACVP data for ML-KEM and ML-DSA, among others. Scripts extract them (tools/regen-vectors.sh and tools/regen-pq-vectors.sh); nobody types them in. Tests compare every intermediate value byte for byte, in both roles. The common tests, vectors included, run on the JVM, Linux, macOS, the iOS simulator, JS and Wasm; the ACVP vectors run on the JVM, where the post-quantum backend is.
Interop
CI builds libcoap and libedhoc from pinned sources and runs kcoap against them: as client and as server, as Initiator and as Responder.
libcoap’s maintainers include RFC authors, and libedhoc is an independent EDHOC implementation in C. Against libcoap 4.3.5b, kcoap is tested over UDP, TCP and WebSockets, with Block-wise, Observe, Q-Block, Echo and OSCORE, and as a TLS client over coaps+tcp and coaps+ws. libcoap’s forward-proxy also stands between a WebSocket-only kcoap client and a kcoap device on UDP, with OSCORE, EDHOC and the combined request end to end. Against libedhoc, every cipher suite and method both implement runs in both roles, and a session passes only when both sides derive the same OSCORE Master Secret and Salt, identifiers and exporter output, before and after a key update.
Not cross-tested yet: EDHOC over CoAP and the combined request against an independent peer; cipher suites 1, 3, 5 and 6, which libedhoc lacks; DTLS; kcoap as a TLS server; the proxy path from a real browser; interop under systematic network impairment. Interop runs on the JVM target; the protocol code is the same common code everywhere.
| Test | Peer | kcoap as client or Initiator | kcoap as server or Responder |
|---|---|---|---|
| CoAP over UDPBlock-wise, Observe, discovery | libcoap v4.3.5b | yes | yes |
| CoAP over TCP and WebSocketsCSM, Ping/Pong, BERT, Observe | libcoap v4.3.5b | yes | yes |
| TLS, coaps+tcp and coaps+wstrusted, pinned, refused, other host | libcoap v4.3.5b | yes | not yet |
| Q-Block, RFC 9177bursts with loss, Observe, fallback | libcoap v4.3.5b | yes | yes |
| Address verification4.01 with Echo, RFC 9175 | libcoap v4.3.5b | does not apply | yes |
| OSCORE, RFC 8613through the stack, over UDP, TCP, WS | libcoap v4.3.5b | yes | yes |
| Through libcoap’s proxyWebSocket to UDP: OSCORE, EDHOC | libcoap v4.3.5b | yes | yes |
| EDHOC, RFC 9528suites 0, 2, 4, 24 × methods 0–3 | libedhoc 0363bd3 | yes | yes |
| Post-quantum EDHOCsuite −24: ML-KEM-512, ML-DSA-44 | libedhoc 0363bd3 | yes | yes |
| EDHOC over CoAP, RFC 9668kcoap ↔ kcoap only | no independent peer yet | not yet | not yet |
| Suite | Algorithms | Methods | Credentials |
|---|---|---|---|
| 0 | X25519, Ed25519, AES-CCM-16-64-128 | 0, 1, 2, 3 | CCS by kid; an Ed25519 x5chain, with kcoap as Initiator |
| 2 | P-256, ES256, AES-CCM-16-64-128 | 0, 1, 2, 3 | CCS by kid |
| 4 | X25519, Ed25519, ChaCha20-Poly1305 | 0, 1, 2, 3 | CCS by kid; an Ed25519 x5chain, with libedhoc as Initiator |
| 24 | P-384, ES384, A256GCM | 0, 1, 2, 3 | CCS by kid |
| −24 | ML-KEM-512, ML-DSA-44, SHAKE256 | 0 | CCS with an AKP key; ML-DSA-44 x5chain |
Each is listed in the interop notes and pinned by an upstream… test where it can be. kcoap does not copy them.
The interop notes record that no deviation from RFC 9528 or draft-ietf-lake-pqsuites-02 was found on kcoap’s side.
The peers build from source on every CI run, libcoap at tag v4.3.5b and libedhoc at commit 0363bd3, with kcoap’s own edhoc_peer around libedhoc. Q-Block soaks run against libcoap at 10 % loss on both sides.
A test runs each peer in Docker and plays one role while kcoap plays the other; for EDHOC, both sides then compare what they derived.
Post-quantum
The KEM-based key exchange of draft-ietf-lake-pqsuites, as libedhoc’s private cipher suite −24: ML-KEM-512 for the key exchange, ML-DSA-44 for signatures.
kcoap-crypto-bc, which wraps the classical backend you pass. An Android app builds and shrinks with it, but has not run it on a device. Other platforms are still to do. Over CoAP, suite −24 runs between kcoap’s own client and server in the sequential flow, its large messages block-wise; not yet in the combined request, nor against another CoAP implementation.PostQuantum.kt
// ML-KEM and ML-DSA on Bouncy Castle, around the classical backend you pass
val crypto = BouncyCastleCryptoBackend(DefaultCryptoBackend())
val initiatorConfig = EdhocInitiatorConfig(
method = EdhocMethod.SIGNATURE_SIGNATURE,
cipherSuites = listOf(CipherSuite.SUITE_PQC_1), // suite −24
credentials = listOf(credential), // an ML-DSA-44 key in a CCS
credentialResolver = TrustedCredentials(crypto, listOf(peerCredential)),
)Names checked against kcoap-crypto-bc, kcoap-crypto-default and kcoap-edhoc; composed from PostQuantumBouncyCastleTest.
Q-Block
Large bodies travel in bursts of Non-confirmable blocks, and a lost block is asked for again on its own, without restarting the transfer.
Evidence: every RFC 9177 figure on virtual time; soaks of 20 seeds at 10 % and 30 % loss; libcoap 4.3.5b in both roles. Open: the nightly soak is not scheduled in CI yet. ADR 0006.
The client sends a body as a burst of six Non-confirmable blocks, numbered 0 to 5, without waiting between them. Block 3 is lost on the way. The server waits NON_RECEIVE_TIMEOUT, then answers 4.08 Request Entity Incomplete with the list of missing blocks: 3. The client sends only block 3 again, and the server answers 2.04 Changed once the whole body has arrived.
QBlock.kt
// Server: Q-Block is off by default
val serverConfig = CoapServerConfig(
qBlock = QBlockServerConfig(isEnabled = true),
)
val transport = KtorUdpTransport.bind(port = 5683)
val server = CoapServer(transport, scope, serverConfig) {
// resources
}
// Client: OFF by default; PROBE asks each server once
val clientConfig = CoapClientConfig {
qBlock = QBlockClientConfig(mode = QBlockMode.PROBE)
}
val client = CoapClient(KtorUdpTransport.bind(), scope, clientConfig)
// Non-confirmable requests get Non-confirmable bursts;
// Confirmable ones go block by block.
val body = client.get("coap://192.0.2.1/big") { nonConfirmable() }.payloadThe settings and calls of the guide’s Q-Block example, which GuideExamplesTest runs over real UDP in CI.
Security
With OSCORE configured, nothing unprotected gets through by accident, in either direction.
MessageSecurityRequired by default once security is set. A refused request gets 4.01, or 4.03 with an identity, before any handler, buffer, observation or burst.UNVERIFIED_RESPONSE.allowUnprotected says otherwise./.well-known/core lists only what the caller may use.A request arrives over UDP, TCP or WebSockets. The server looks up the resource and its access policy, which is MessageSecurityRequired by default when message security is set. If the policy refuses the request, the server answers 4.01 Unauthorized, or 4.03 Forbidden when the caller has an identity, and nothing else runs. Only an allowed request reaches the option checks, the Block-wise buffers, Observe registration, Q-Block bursts and the address check, and then the handler, which sees the verified identity.
Server.kt
val server = CoapServer(
KtorUdpTransport.bind("0.0.0.0", 5683),
scope,
CoapServerConfig(security = OscoreServer(contexts)),
) {
resource("lights") { // OSCORE only, by default
get { CoapResponse.content("on for ${securityIdentity?.description}") }
}
resource("status") {
access = AccessPolicy.Public // for anyone, with or without OSCORE
get { CoapResponse.content("up") }
}
}The README’s quick start, checked against the sources. ADR 0008 records the decision; AccessPolicyTest and UnverifiedResponseTest pin it.
Design
The protocol cores take bytes and the time, and return bytes and timers. Sockets and clocks live in thin adapters, so each layer is tested with fixed vectors on virtual time.
EdhocInitiator and EdhocResponder are public API: message bytes in and out, transport left to you.A state machine such as UdpMessaging, QBlock1Sender, QBlock2Receiver, EdhocInitiator or EdhocResponder has no socket, clock or thread inside. Bytes and the current time go in; bytes to send and the next deadline come out. In production a thin adapter connects it to a socket and a clock. In tests the same machine runs on fixed vectors and virtual time.
Platforms
All protocol code is common Kotlin, with no expect/actual; the build fails a core module that grows code anywhere else.
linuxArm64, no Intel Apple targets.Common Kotlin holds all protocol code, with no expect/actual, and builds for: Android, through the jvm artifacts from API level 26, with JCA; iOS (iosArm64) and macOS (macosArm64) with CryptoKit and CommonCrypto; JVM servers and desktops (jvm, Java 17) with JCA; Linux gateways (linuxX64) with OpenSSL 3; and browsers and Node.js (js and wasmJs) with WebCrypto.
DefaultCryptoBackend on each target. UDP and TCP sockets build for the JVM, Apple and Linux; browsers and Node.js use the WebSocket client.Cryptography
All cryptography goes through one asynchronous CryptoBackend. Protocol code asks what the backend supports, so a platform’s gaps become choices made up front, not failures halfway through a handshake.
DefaultCryptoBackend runs on JCA, CryptoKit and CommonCrypto, OpenSSL 3 or WebCrypto. It probes each algorithm once and remembers the answer.supports(x) is false exactly when the operation would throw. EDHOC offers and accepts only the suites the backend runs.Open: Ed448 and suite 25; post-quantum beyond the JVM; suites per platform printed by the probes, not derived by hand as in platforms.md. ADR 0001.
An EDHOC Initiator is configured with cipher suites 2 and 4. Before the handshake, kcoap asks the crypto backend what it supports. In a browser, WebCrypto has no ChaCha20-Poly1305, which suite 4 needs. So message_1 offers suite 2 only: suite 4 is left out up front instead of failing later.
Build
The rules that keep kcoap portable and its API stable are checks in the build and in CI, not conventions.
Every published module has committed JVM and klib API dumps. checkKotlinAbi fails on any change to them that is not committed with the code.
verifyCommonOnly fails a core module that has main code outside commonMain.
checkAndroidApi checks every jvm jar against the API 26 signature; checkAndroidApiDependencies checks the libraries behind them against a triaged baseline.
verifyNoServerEngine keeps a ktor server engine out of the WebSocket server’s published dependencies: the application chooses it.
Explicit API mode everywhere. @ExperimentalKcoapApi marks what may change in any minor release, @InternalKcoapApi what is not API at all.
koverVerify holds 90 % line coverage, 95 % for kcoap-edhoc. Every commit of a pull request needs a DCO sign-off.
Protocol support
The states are the checklist’s: done, partial, to do or deferred. A partial row works, and names what it still misses.
RFC compliance has the detail section by section; where it says more than the checklist, the checklist wins.
From top to bottom: your application, which uses CoapClient and CoapServer; the request and response layer with Observe, Block-wise, Q-Block and Echo; OSCORE, which protects messages end to end on every transport; CoAP messaging, RFC 7252 over datagrams and RFC 8323 over streams; and the transports UDP (coap), TCP (coap+tcp) and WebSocket (coap+ws). EDHOC sits beside the request and OSCORE layers: it runs over CoAP and hands its keys to OSCORE. Under the transports, TLS clients: coaps+tcp on the JVM, and coaps+ws where the WebSocket engine checks the server; servers terminate TLS at a reverse proxy. Not built yet: DTLS, which comes last.
| Protocol | RFC | State | Open, and the checklist rows |
|---|---|---|---|
| CoAP over UDP: messaging, requests, options, URIs | 7252 | partial | Caching (§5.6), proxying (§5.7) and multicast (§8) to do; option lengths (§5.4.3) and dot segments in URIs (§5.10.1) open; DTLS last. coap-core-1 to 9, x1 to x5 |
Link format, /.well-known/core | 6690 | done | Multicast discovery waits for multicast. coap-core-10 |
| Observe | 7641 | partial | The Content-Format of notifications and 4.06 (§4.2). coap-core-11 |
| Block-wise transfers | 7959 | partial | If-None-Match is repeated after the first Block1 block (§2.10); inner Block-wise only. coap-core-12 |
| Q-Block | 9177 | done | Off by default; §4.8 (multicast) and §8–9 (proxies) not applicable. coap-core-13 |
| FETCH, PATCH, iPATCH | 8132 | partial | The FETCH body is not part of the observation and Block2 keys. coap-core-14 |
| No-Response | 7967 | partial | The server is done; the client still waits for its timeout. coap-core-15 |
| Echo, Request-Tag | 9175 | partial | Address verification against amplification is done; server freshness checks (§2.3) outside OSCORE to do. coap-core-16 |
| Hop-Limit | 8768 | partial | The option and code exist; processing belongs to proxies. coap-core-17 |
| Too Many Requests (4.29) | 8516 | done | A 4.29 with Max-Age, and a client helper that waits it out; which clients ask too often is the application’s to decide. coap-core-18 |
| Extended tokens | 8974 | to do | Scope not decided. coap-core-19 |
| CoAP over TCP and WebSockets | 8323 | partial | CSM, Ping/Pong, Release, Abort, BERT and Observe work. TLS: a coaps+tcp client on the JVM, TLS 1.2 without ALPN, cross-tested with coaps+ws; no TLS listener. coap-core-20, x9 |
| DTLS 1.2 | 6347, 7925, 9146 | deferred | Interfaces only; the engine comes last. coap-core-21 |
| OSCORE | 8613 | partial | Works through an OSCORE-unaware forward proxy, cross-tested through libcoap’s. Outer Block-wise, protected signaling over TCP, a proxy of kcoap’s own, OSCORE over HTTP and Appendix B.2 to do; nonce reuse after sequence-number exhaustion (§7.2.1) open. oscore-1 to 11, x1 to x6 |
| 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; no independent peer for suites 1, 3, 5 and 6. edhoc-1 to 9 |
| Post-quantum EDHOC, suite −24 | draft-ietf-lake-pqsuites | partial | Done on the JVM; an Android app builds with it but has not run it on a device; other platforms to do. edhoc-2, kmp-8 |
| EDHOC over CoAP, into OSCORE, combined request | 9528 App. A, 9668 | partial | The forward flow and the combined request work end to end, with MUSTs still missing: the client’s EDHOC error after a failed message_2 or message_4, the sequential fallback for a large request, Outer Block1 reassembly. The reverse flow is to do, and there is no independent peer yet. edhoc-oscore-1 to 7 |
| CBOR, COSE, CWT Claims Sets | 8949, 9052, 8392 | partial | What OSCORE and EDHOC need is done; full COSE messages, CWT validation and X.509 path validation to do. foundations-1 to 5, x1 to x6 |
Defaults
What kcoap does without being asked, and where it leaves a decision to you.
Before a Q-Block burst or an Observe registration with Q-Block to an unverified address, the server checks the address with a 4.01 and Echo (RFC 9175). ALL_RESPONSES also covers every response more than three times its request.
OSCORE keeps a replay window of 32, and one per request for bodies of several responses. After a restart, the first request with old keys is challenged with Echo (Appendix B.1.2), unless the keys are new.
Pre-shared keys need a durable store, and kcoap has no default: you choose one. Every Partial IV is durable before its nonce is used.
Limits in total and per peer on deduplication entries, Message IDs, concurrent requests, exchanges, observers, connections and bodies hold back floods from forged addresses while real clients are still served; each is reported as an event when reached. The limits.
A pending session answers only the peer that started it. At most 64 pending sessions, 8 per peer; they expire, and their secrets are wiped. Every authentication failure sends the same error.
Logs never contain EDHOC secrets, and secrets are copies wiped after use. No X.509 path validator ships yet: without one, only pinned credentials are trusted.
Do not open a public issue. Report it through GitHub’s private vulnerability reporting, which only the maintainer and you can see, or write to adrian.soltys@seelso.net with “kcoap security” in the subject. SECURITY.md has the details.
Testing
Vectors first, then differential and fuzz tests, simulated networks on virtual time, stress tests on real threads, and live interop. CI runs on every pull request.
AES-CCM, AES-GCM, ChaCha20, SHAKE256, KMAC256 and SEC 1 points against Bouncy Castle; ECDSA encodings against the JDK.
Seeded byte mutation on every target for the CBOR, CoAP, OSCORE, EDHOC, X.509 and DER parsers.
kcoap-testkit loses, duplicates and reorders datagrams, so a 93-second give-up is tested in milliseconds.
Concurrency tests on the thread pools of the JVM and Linux targets, and on the event loop of the web targets.
The common tests run in CI on the JVM, Linux, macOS, the iOS simulator, and JS and Wasm on Node.js. Kover measures coverage on the JVM.
libcoap and libedhoc, built from pinned sources in Docker, in both roles. The matrix.
| Job | Runner | What it runs |
|---|---|---|
| Unit tests and build checks | Linux | Every unit test on the JVM, Linux native, JS and Wasm; the ABI, common-only, server-engine and Android API checks; the coverage floor |
| Interop | Linux, Docker | The libcoap and libedhoc cross-tests, TLS and libcoap’s forward-proxy included, with images built from pinned sources |
| Native tests | macOS | The common tests on macOS and the iOS simulator, a Swift smoke test against a framework of kcoap-coap, and the ABI check with the Apple klibs |
| Browser | Linux | The WebSocket client in headless Chrome against a JVM listener |
| Android consumer | Linux | The sample app at minSdk 26: R8 on both release variants, lint, unit tests |
| API reference | Linux | The API reference built with Dokka |
| Website | Linux | The checks of this website, in a workflow of its own that runs when the site changes |
Pull requests also run the DCO sign-off check. Testing describes each level and the one-command suites.