kcoap-coap-message
CoAP's wire vocabulary: the message model, options, URIs and link format, the codecs for every CoAP framing, and the message-security SPI that OSCORE implements. Common Kotlin with no I/O, no coroutines and no state of its own; it depends only on kcoap-common and kcoap-transport (for Endpoint and CoapScheme).
It is the stable layer the rest builds on. ../kcoap-coap/README.md, the endpoint stack with CoapClient and CoapServer, depends on it with api, so an application that uses the stack gets it without declaring it. ../kcoap-oscore/README.md depends on this module only, not on the stack, so OSCORE can protect messages of another CoAP stack, a proxy or a gateway.
Such a caller takes over what kcoap-coap's stack does with the message-security SPI, as the KDoc of src/commonMain/kotlin/dev/kcoap/coap/security/MessageSecurity.kt and src/commonMain/kotlin/dev/kcoap/coap/security/ResponseVerification.kt states. The security layer only verifies and reports, so a caller that skips one of these duties fails open (kcoap-oscore's README gives them with their RFC 8613 sections):
Never process the
messageof anUnprotectedRequestwhosechallengeis not null; sendprotectResponse(challenge)instead (OSCORE's freshness check after a restart).Treat null from
unprotectRequestas an unauthenticated request, refused unless the resource is public (../docs/adr/0008-fail-closed-message-security.md).Act only on
ResponseVerification.Verified; never repeat a request, continue a body or end an observation onUnverified.Assign the token and the Message ID before
protectRequest, and keep them.Use one
UnprotectedRequestfor every response to its request, notifications and Q-Block blocks included, and oneProtectedRequestfor every response it verifies.
Packages
--------The packages kept their names when they moved here from kcoap-coap, so imports did not change.
| Package | What |
|---|---|
dev.kcoap.coap | CoapMessage and its Builder, CoapCode, CoapMessageType, CoapOption, OptionSet and its Builder, the option registry CoapOptions with OptionDefinition and each option's OSCORE class, ContentFormat, BlockOption, CoapUri, the application model CoapRequest and CoapResponse, LinkFormat and WebLink (RFC 6690), and SignalingOptions (RFC 8323 §5.2) |
dev.kcoap.coap.codec | MessageCodec; UdpMessageCodec (RFC 7252 §3); ReliableMessageCodec for TCP and WebSocket framing and ReliableStreamDecoder for byte streams (RFC 8323 §3.2, §4.2); CoapFormatException. OptionCodec, the option encoding shared with kcoap-oscore, is @InternalKcoapApi |
dev.kcoap.coap.security | The message-security SPI: ClientMessageSecurity, ProtectedRequest, ServerMessageSecurity, UnprotectedRequest, SecurityIdentity, ResponseVerification, MessageSecurityException |
val request = CoapMessage.request(CoapCode.GET) {
messageId = 0x1234
token = byteArrayOf(0x4a)
options { uriPath("sensors/temperature") }
}
val datagram = UdpMessageCodec.encode(request) // RFC 7252 §3
check(UdpMessageCodec.decode(datagram) == request)
val frame = ReliableMessageCodec.WebSocket.encode(request) // RFC 8323 §4.2: no type, no Message IDImplemented
-----------Messages, RFC 7252 §3 and §5.10: header, token, options and payload; every option of the registry with its format, length bounds and repeatability (Uri-, Location-, ETag, If-Match, If-None-Match, Content-Format, Accept, Max-Age, Proxy-*, Size1, plus Observe from RFC 7641, Block1, Block2 and Size2 from RFC 7959, No-Response from RFC 7967, OSCORE from RFC 8613, Hop-Limit from RFC 8768, Echo and Request-Tag from RFC 9175, Q-Block1 and Q-Block2 from RFC 9177, EDHOC from RFC 9668), and each option's OSCORE class (RFC 8613 §4.1). Unknown options are kept and treated as Class E.
URIs, RFC 7252 §6 and RFC 8323 §8:
coap,coaps,coap+tcp,coaps+tcp,coap+wsandcoaps+wsURIs to and from Uri-Host, Uri-Port, Uri-Path and Uri-Query, with percent-encoding.Link format, RFC 6690: parsing and serializing
/.well-known/coredocuments, with theoscattribute of RFC 8613 §9.Caller input and peer input.
CoapUri.parseandLinkFormat.parsetake text the application supplies and throwIllegalArgumentExceptionon a malformed one, a mistake of the caller.CoapUri.parseOrNullandLinkFormat.parseOrNulltake text a peer sent, such as a/.well-known/coredocument and the link targets in it, and return null instead of throwing.CoapUri.fromOptionsrebuilds a URI from options the application built;CoapUri.fromOptionsOrNullfrom the options of a received request, returning null for one no URI has, such as an empty Uri-Port (the port 0).CoapUri.parselistsIllegalArgumentExceptionin@Throws, since URIs are often typed in: on Apple platforms Swift catches a malformed one as anNSError(try CoapUri.Companion.shared.parse(text:)).Value types:
CoapRequestandCoapResponseare equal by their parts (the body by content);CoapUri,WebLinkand the messages copy the lists and byte arrays they are given.CoapResponse.from(message)takes the response out of a message;CoapMessageType.fromValuereturns null for a value no type has.Codecs: the UDP header (RFC 7252 §3), the TCP and WebSocket framings of RFC 8323 §3.2 and §4.2, and a stream decoder that bounds the message size. Malformed input fails with
CoapFormatException, never with another exception.Message-security SPI: where RFC 8613 Figure 1 puts OSCORE, between the request/response layer and the messaging layer. kcoap-coap's stack calls it, kcoap-oscore implements it, and kcoap-edhoc-oscore decorates it (RFC 9668). Its four operations list
MessageSecurityExceptionandCancellationExceptionin@Throws, which every implementation inherits;MessageSecurityExceptionis a signal between the layers, not aKcoapException, and kcoap-coap translates it at its boundary.
Not here
--------Everything that sends, waits or keeps state per peer is in kcoap-coap: the endpoint and its messaging layers, tokens and Message IDs, Block-wise, Observe, Q-Block, the client and the server, and CoapException, which reports how an exchange failed.
Verified by
-----------UdpMessageCodecTest: RFC 8613 Appendix C messages byte for byte, and the RFC 7252 §3 header rules.ReliableMessageCodecTest: the RFC 8323 §3.2 length forms and the WebSocket framing (§4.2).CodecFuzzTest: mutated messages fromkcoap-testkit'sByteMutatoreither decode or fail withCoapFormatException.CoapModelTestandCoapOptionsTest: codes, options, builders, Block options, URIs, the option registry, andCoapRequestandCoapResponse.LinkFormatTest: the RFC 6690 §5 example document both ways, flags, escapes and quoted commas, malformed documents, and the §4.1 query filters.PeerInputFuzzTest: link-format documents and URIs mutated byByteMutator, as a peer might send them:parseOrNullnever throws,IllegalArgumentExceptionleast of all, andparseagrees with it.SignalingOptionsTest: the RFC 8323 §11.2 registry per signaling code, and how a signaling message prints its options (§5.2).MessageSecurityTypesTest: the SPI's values on their own:MessageSecurityException's defaults and its copied error body,UnprotectedRequest.challenge,ResponseVerification.In kcoap-coap, how the stack uses these types:
/.well-known/coreinDiscoveryTest, the CSM, Ping, Pong, Release and Abort signals inSignalTest, and the message-security SPI with a fake OSCORE-like layer inMessageSecurityTest,AccessPolicyTestandUnverifiedResponseTest. kcoap-oscore implements the SPI against RFC 8613 Appendix C.Line coverage: this module's own tests cover 94.0% of its lines (
./gradlew :kcoap-coap-message:koverXmlReport). The root Kover report (./gradlew koverXmlReport), which counts the tests of every module, gives 98.7% fordev.kcoap.coap, 100% fordev.kcoap.coap.codecand 93.8% fordev.kcoap.coap.security.