Features

What kcoap does, and how it is checked

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

RFC vectors, byte for byte

Where a specification prints test vectors, kcoap replays them and compares every intermediate value, not only the result.

  • Done: OSCORE: RFC 8613 Appendix C.1 to C.8, from context derivation to protected messages, on both sides.
  • Done: EDHOC: both traces of RFC 9529, every printed value, as Initiator and as Responder, and the invalid messages of its section 4.
  • Done: The combined EDHOC and OSCORE request of RFC 9668 Figure 4, and the RFC 8323 framing of Figure 5 and Figures 11 and 12.
  • Done: Every Q-Block figure of RFC 9177, 2 to 20, as a script on virtual time over the real messaging layer.
  • Done: Cryptography: all 24 AES-CCM packets of RFC 3610, RFC 5869 HKDF, FIPS 197, SP 800-185 KMAC256 samples 1 to 4, and a subset of NIST’s ACVP vectors for ML-KEM and ML-DSA.
Evidence and open items
  • Rfc8613VectorsTest, Rfc9529TraceTest, Rfc9529InvalidTracesTest, QBlockFiguresTest, AesCcmTest, MlKemKnownAnswerTest, MlDsaKnownAnswerTest.
  • Open: one case each for RFC 7748, RFC 8032 and FIPS 202; KMAC256 samples 5 and 6; no CI check yet that the scripts reproduce the committed vectors.
Test vectors, from the specification to every targetVectors 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.RFC 8613Appendix CRFC 9529traces 1 and 2NIST ACVPML-KEM, ML-DSAExtracted by scripts, not typed intools/regen-vectors.sh · tools/regen-pq-vectors.shCompared byte for byteevery intermediate value, in both rolesJVMLinuxmacOSiOS simJSWasm
Read the diagram as text

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.

Vectors are extracted by scripts from the published documents and the pinned ACVP data. The common tests run on every target; the ACVP vectors run on the JVM, where the post-quantum backend is.

Interop

Live interop in both roles

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.

Interop matrixAgainst libcoap v4.3.5b, kcoap runs as client and as server for CoAP over UDP, CoAP over TCP and WebSockets, Q-Block (RFC 9177) and OSCORE (RFC 8613); as client for TLS over coaps+tcp and coaps+ws; and as server for address verification with Echo (RFC 9175). kcoap also runs as client and as server on either side of libcoap’s forward-proxy, from WebSockets to UDP, with OSCORE, EDHOC and the combined request. Against libedhoc 0363bd3, kcoap runs as Initiator and as Responder for EDHOC (RFC 9528) suites 0, 2, 4 and 24 with methods 0 to 3, and for the post-quantum suite -24 with ML-KEM-512 and ML-DSA-44. EDHOC over CoAP and the combined request of RFC 9668 have no independent EDHOC peer yet; they are tested kcoap against kcoap.Cross-tested in CIagainst pinned buildsClientInitiatorServerResponderlibcoap v4.3.5bCoAP over UDPBlock-wise, Observe, discoveryCoAP over TCP and WebSocketsCSM, Ping/Pong, BERT, ObserveTLS, coaps+tcp and coaps+wstrusted, pinned, refused, other hostQ-Block, RFC 9177bursts with loss, Observe, fallbackAddress verification4.01 with Echo, RFC 9175OSCORE, RFC 8613through the stack, over UDP, TCP, WSThrough libcoap’s proxyWebSocket to UDP: OSCORE, EDHOClibedhoc 0363bd3EDHOC, RFC 9528suites 0, 2, 4, 24 × methods 0–3Post-quantum EDHOCsuite −24: ML-KEM-512, ML-DSA-44no independent peer yetEDHOC over CoAP, RFC 9668kcoap ↔ kcoap only
Read the diagram as text
TestPeerkcoap as client or Initiatorkcoap as server or Responder
CoAP over UDPBlock-wise, Observe, discoverylibcoap v4.3.5byesyes
CoAP over TCP and WebSocketsCSM, Ping/Pong, BERT, Observelibcoap v4.3.5byesyes
TLS, coaps+tcp and coaps+wstrusted, pinned, refused, other hostlibcoap v4.3.5byesnot yet
Q-Block, RFC 9177bursts with loss, Observe, fallbacklibcoap v4.3.5byesyes
Address verification4.01 with Echo, RFC 9175libcoap v4.3.5bdoes not applyyes
OSCORE, RFC 8613through the stack, over UDP, TCP, WSlibcoap v4.3.5byesyes
Through libcoap’s proxyWebSocket to UDP: OSCORE, EDHOClibcoap v4.3.5byesyes
EDHOC, RFC 9528suites 0, 2, 4, 24 × methods 0–3libedhoc 0363bd3yesyes
Post-quantum EDHOCsuite −24: ML-KEM-512, ML-DSA-44libedhoc 0363bd3yesyes
EDHOC over CoAP, RFC 9668kcoap ↔ kcoap onlyno independent peer yetnot yetnot yet
A filled mark runs in CI’s interop job; a dash does not apply; a dashed circle is not cross-tested yet.

EDHOC sessions against libedhoc

Every row runs with kcoap as Initiator and as Responder, except the two x5chain cases, which run in the role named. Also covered: suite negotiation with error code 2 both ways, tampered messages answered with error code 1, and EAD items.
SuiteAlgorithmsMethodsCredentials
0X25519, Ed25519, AES-CCM-16-64-1280, 1, 2, 3CCS by kid; an Ed25519 x5chain, with kcoap as Initiator
2P-256, ES256, AES-CCM-16-64-1280, 1, 2, 3CCS by kid
4X25519, Ed25519, ChaCha20-Poly13050, 1, 2, 3CCS by kid; an Ed25519 x5chain, with libedhoc as Initiator
24P-384, ES384, A256GCM0, 1, 2, 3CCS by kid
−24ML-KEM-512, ML-DSA-44, SHAKE2560CCS with an AKP key; ML-DSA-44 x5chain

Deviations found in the peers

Each is listed in the interop notes and pinned by an upstream… test where it can be. kcoap does not copy them.

  • Open: libcoap 4.3.5b protects only one response per request, so Q-Block under OSCORE is cross-tested kcoap against kcoap only.
  • Open: libcoap answers a request with both Block2 and Q-Block2 with 4.00 instead of 4.02, and keeps Q-Block for a whole session.
  • Open: libcoap’s WebSocket server aborts on frames above 1472 bytes, so the tests cap its message size.
  • Open: libedhoc’s Responder supports only its last configured suite, and accepts unknown critical EAD without a callback.
  • Open: libcoap’s forward-proxy reaches devices only on port 5683, drops an OSCORE request that names its target in Proxy-Uri, sends a deregistration on a new token, and corrupts request bodies of several blocks, which keeps post-quantum EDHOC off that path (ADR 0009).

On kcoap’s side

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.

Interop details

Post-quantum

Post-quantum EDHOC

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.

  • Done: Round trips with real ML-KEM and ML-DSA on Bouncy Castle 1.86.
  • Done: ML-KEM and ML-DSA checked against a subset of NIST’s ACVP vectors, at a pinned ACVP-Server commit.
  • Done: Live against libedhoc’s liboqs build, in both roles, with CCS and ML-DSA-44 X.509 credentials.
  • Done: Method 0 only: methods 1 to 3 need static Diffie-Hellman keys, which a KEM suite has not, so they are refused.
  • Open: On the JVM only, through 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.

Suite −24 in numbers

Key exchange
ML-KEM-512
Signatures
ML-DSA-44
EDHOC AEAD
AES-CCM-16-128-128
EDHOC hash
SHAKE256, so Extract and Expand are KMAC256
OSCORE
AES-CCM-16-64-128 and SHA-256
message_1
806 bytes, with an 800-byte encapsulation key
message_2
a 768-byte ciphertext and a 2420-byte signature
Code point
−24, in RFC 9528’s private-use range, as libedhoc uses it

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

Q-Block, RFC 9177

Large bodies travel in bursts of Non-confirmable blocks, and a lost block is asked for again on its own, without restarting the transfer.

  • Done: Client and server, uploads (Q-Block1) and downloads (Q-Block2), over UDP, TCP and WebSockets.
  • Done: With Observe: each change goes out as one body, with a new ETag.
  • Done: Under OSCORE, opt-in on both sides, with a replay window per request.
  • Done: Before a burst to an unverified address, the server checks it with Echo.
  • Done: Off by default. A client set to probe asks each server once and falls back to RFC 7959 Block-wise.

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.

A Q-Block1 burst that loses block 3The 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.Clientsends a bodyServerreceives itBURST OF NON-CONFIRMABLE BLOCKS0123lost45waitsNON_RECEIVE_TIMEOUT4.08 Request Entity Incompletemissing blocks: 33block 3 only, sent again2.04 Changedthe whole body has arrived
Read the diagram as text

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.

A Q-Block1 upload, simplified from RFC 9177 Figures 4 and 5: six blocks in one burst, block 3 lost and sent again on its own.

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() }.payload

The settings and calls of the guide’s Q-Block example, which GuideExamplesTest runs over real UDP in CI.

Security

Fail-closed message security

With OSCORE configured, nothing unprotected gets through by accident, in either direction.

  • Done: Server: every resource has an access policy, 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.
  • Done: Client: it acts only on responses it verified. An unprotected error, which anyone on the path can send, is never repeated with its Echo or continued; the request fails with UNVERIFIED_RESPONSE.
  • Done: No silent plaintext: a request without a context fails instead of going out unprotected, unless allowUnprotected says otherwise.
  • Done: /.well-known/core lists only what the caller may use.
What a server with message security does before any handler runsA 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.Request arrivesover UDP, TCP or WebSocketsResource lookupthe resource and its access policyAccess policyMessageSecurityRequired by default4.01 or 4.03nothing else runsnoallowedOption checks, Block-wise buffers, Observe,Q-Block bursts, the address checkYour handlersees the verified identity: securityIdentity
Read the diagram as text

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.

The access policy runs right after the resource lookup, so a refused request costs the server no buffer, observation or burst.

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

Sans-IO state machines

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.

  • Done: CoAP messaging over datagrams and over streams, and the four Q-Block machines, run inside the endpoint.
  • Done: EDHOC’s EdhocInitiator and EdhocResponder are public API: message bytes in and out, transport left to you.
  • Done: OSCORE protects and verifies messages without the endpoint, so a proxy or another CoAP stack can use it.
  • Done: Time and randomness are injected; ephemeral keys too, which is how the RFC 9529 traces replay.
  • Open: A public sans-IO CoAP engine, for embedding in Netty or Vert.x event loops, is not built yet.
A sans-IO state machineA 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.NO SOCKET, NO CLOCK, NO THREAD INSIDEState machineUdpMessagingQBlock1SenderEdhocInitiatorbytes innowbytes outnext deadlineIn productiona thin adapter: socket and clockIn testsfixed vectors, virtual time
Read the diagram as text

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.

The same state machine runs on a socket in production and on fixed vectors and virtual time in the tests.

Platforms

One code base, every target

All protocol code is common Kotlin, with no expect/actual; the build fails a core module that grows code anywhere else.

  • Done: The same common tests run in CI on the JVM, Linux, macOS, the iOS simulator, and JS and Wasm on Node.js.
  • Done: Android uses the JVM artifacts from API level 26; CI checks the API level and builds a sample app with R8.
  • Done: Tests choose algorithms by what the backend supports, never by the platform they run on.
  • Open: Not yet run on an Android device or an iPhone. No linuxArm64, no Intel Apple targets.

Setup by platform

One common code base, seven platformsCommon 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.Common Kotlinall protocol code, no expect/actualAndroidjvm, API 26+JCAiOSiosArm64CryptoKitmacOSmacosArm64CryptoKitJVMjvm, Java 17JCALinuxlinuxX64OpenSSL 3Browsersjs, wasmJsWebCryptoNode.jsjs, wasmJsWebCrypto
Read the diagram as text

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.

The cryptography under DefaultCryptoBackend on each target. UDP and TCP sockets build for the JVM, Apple and Linux; browsers and Node.js use the WebSocket client.

Cryptography

Capability-aware crypto

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.

  • Done: DefaultCryptoBackend runs on JCA, CryptoKit and CommonCrypto, OpenSSL 3 or WebCrypto. It probes each algorithm once and remembers the answer.
  • Done: supports(x) is false exactly when the operation would throw. EDHOC offers and accepts only the suites the backend runs.
  • Done: Small, public-data gaps get common-code fallbacks, such as AES-CCM on the AES block and point decompression. Secret-key algorithms do not.
  • Done: Private keys are opaque handles that protocol code never reads, so a hardware backend can hold them. None ships yet.

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.

EDHOC offers only the suites the backend can runAn 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.CONFIGUREDEdhocInitiatorConfigsuite 2suite 4ASKEDcrypto.supports(...)In a browser: no ChaCha20-Poly1305, which suite 4 needsOFFERED IN MESSAGE_1suite 2suite 4 left out, not failed later
Read the diagram as text

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.

In a browser, WebCrypto has no ChaCha20-Poly1305, so an Initiator configured with suites 2 and 4 offers suite 2 only.

Build

A build that guards the API

The rules that keep kcoap portable and its API stable are checks in the build and in CI, not conventions.

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.

Common-only cores

verifyCommonOnly fails a core module that has main code outside commonMain.

Android API level 26

checkAndroidApi checks every jvm jar against the API 26 signature; checkAndroidApiDependencies checks the libraries behind them against a triaged baseline.

No hidden server engine

verifyNoServerEngine keeps a ktor server engine out of the WebSocket server’s published dependencies: the application chooses it.

Explicit API and opt-in markers

Explicit API mode everywhere. @ExperimentalKcoapApi marks what may change in any minor release, @InternalKcoapApi what is not API at all.

Coverage floor and DCO

koverVerify holds 90 % line coverage, 95 % for kcoap-edhoc. Every commit of a pull request needs a DCO sign-off.

Protocol support

The state of every protocol

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.

The kcoap protocol stackFrom 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.Your applicationCoapClient and CoapServer: suspend calls, Flow for ObserveRequest / responseObserve · Block-wise · Q-Block · EchoOSCOREend to end, on every transportEDHOCRFC 9528key exchangeover CoAPkeysCoAP messagingRFC 7252 over datagrams · RFC 8323 over streamsUDPcoap://TCPcoap+tcp://WebSocketcoap+ws://TLS clients: coaps+tcp, coaps+wsDTLS: last
Read the diagram as text

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.

EDHOC establishes the keys; OSCORE uses them on every request, over any of the three transports.
ProtocolRFCStateOpen, and the checklist rows
CoAP over UDP: messaging, requests, options, URIs7252partialCaching (§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/core6690doneMulticast discovery waits for multicast. coap-core-10
Observe7641partialThe Content-Format of notifications and 4.06 (§4.2). coap-core-11
Block-wise transfers7959partialIf-None-Match is repeated after the first Block1 block (§2.10); inner Block-wise only. coap-core-12
Q-Block9177doneOff by default; §4.8 (multicast) and §8–9 (proxies) not applicable. coap-core-13
FETCH, PATCH, iPATCH8132partialThe FETCH body is not part of the observation and Block2 keys. coap-core-14
No-Response7967partialThe server is done; the client still waits for its timeout. coap-core-15
Echo, Request-Tag9175partialAddress verification against amplification is done; server freshness checks (§2.3) outside OSCORE to do. coap-core-16
Hop-Limit8768partialThe option and code exist; processing belongs to proxies. coap-core-17
Too Many Requests (4.29)8516doneA 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 tokens8974to doScope not decided. coap-core-19
CoAP over TCP and WebSockets8323partialCSM, 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.26347, 7925, 9146deferredInterfaces only; the engine comes last. coap-core-21
OSCORE8613partialWorks 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 249528partialSuite 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 −24draft-ietf-lake-pqsuitespartialDone 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 request9528 App. A, 9668partialThe 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 Sets8949, 9052, 8392partialWhat 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

Security defaults

What kcoap does without being asked, and where it leaves a decision to you.

Amplification

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.

Replay and freshness

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.

Sequence numbers

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.

Bounded state

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.

EDHOC sessions

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.

Secrets and trust

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.

Found a vulnerability?

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

How kcoap is tested

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.

Differential tests

AES-CCM, AES-GCM, ChaCha20, SHAKE256, KMAC256 and SEC 1 points against Bouncy Castle; ECDSA encodings against the JDK.

Fuzzing

Seeded byte mutation on every target for the CBOR, CoAP, OSCORE, EDHOC, X.509 and DER parsers.

Lossy networks on virtual time

kcoap-testkit loses, duplicates and reorders datagrams, so a 93-second give-up is tested in milliseconds.

Stress on real threads

Concurrency tests on the thread pools of the JVM and Linux targets, and on the event loop of the web targets.

Same tests everywhere

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.

Interop

libcoap and libedhoc, built from pinned sources in Docker, in both roles. The matrix.

What CI runs

JobRunnerWhat it runs
Unit tests and build checksLinuxEvery unit test on the JVM, Linux native, JS and Wasm; the ABI, common-only, server-engine and Android API checks; the coverage floor
InteropLinux, DockerThe libcoap and libedhoc cross-tests, TLS and libcoap’s forward-proxy included, with images built from pinned sources
Native testsmacOSThe 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
BrowserLinuxThe WebSocket client in headless Chrome against a JVM listener
Android consumerLinuxThe sample app at minSdk 26: R8 on both release variants, lint, unit tests
API referenceLinuxThe API reference built with Dokka
WebsiteLinuxThe 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.