EdhocClientHandshake
The client (EDHOC Initiator) side of EDHOC over CoAP, forward message flow (RFC 9528 Appendix A.2.1).
It speaks the application model of kcoap-coap-message and is independent of the endpoint: exchange sends one CoapRequest to the EDHOC resource path of server and returns its CoapResponse, so a CoapClient (client::request, which over wires), another carrier or a test double can carry it.
val handshake = EdhocClientHandshake.over(client, CoapUri.parse("coap://192.0.2.1"), config, crypto)
// Three messages, then OSCORE:
val session = handshake.run()
val security = OscoreClient(session.oscore)
// Or two round trips in total, message_3 riding on the first OSCORE request (RFC 9668):
val (session, security) = handshake.runCombined()Cipher suite negotiation (RFC 9528 §6.3) is handled: when the server answers message_1 with error code 2 naming a suite the Initiator supports, message_1 is sent again with that suite. The suites of config are narrowed to those crypto runs on the first run, and config keeps the answer for every later one (docs/adr/0001-crypto-capabilities.md).
Every run fails with an dev.kcoap.edhoc.EdhocException: an EdhocPeerErrorException when the server answered with an EDHOC error, an EdhocTransferException when it answered with something that is not EDHOC, and the exception itself when a step of this side failed. When the OSCORE context cannot be derived at the end (RFC 9528 Appendix A.1) because sequenceStore or crypto threw, the run fails with an EdhocException of error code 1 whose cause is that exception. Whatever exchange throws, such as kcoap-coap's CoapException for a request that got no response, passes through as it is. A run that fails or is cancelled at any step wipes what it holds (RFC 9528 §9.8): the Initiator's ephemeral key X while it waits for message_2, PRK_4e3m and the session's PRK_out and PRK_exporter once message_3 is out.
run and runCombined list KcoapException, the root of both, and CancellationException in @Throws, so on Apple platforms Swift catches a failed handshake as an NSError, with the Kotlin exception in its userInfo under "KotlinException".
Parameters
the scheme, host and port of the server; its path and query are not used.
the EDHOC resource on server, .well-known/edhoc (RFC 9528 §10.7) unless the server mounts it elsewhere, as discovery with resource type core.edhoc tells.
where the handshake's logger comes from, under LogTags.EDHOC.
holds the Sender Sequence Numbers of the contexts this handshake derives. By default (null) each context gets its own EphemeralSequenceNumberStore, which fits EDHOC, whose keys are new with every session, and goes away with the context. Pass a durable store to resume a context after a restart, as oscoreParameters describes. The store keeps one limit per context name, "sid=C_R,rid=C_I" (dev.kcoap.oscore.SecurityContextParameters.name), and those names are not unique across servers: each server chooses its C_R on its own, and nothing on this side makes C_I unique. Two live contexts with one name in one store break its contract and can lead to AEAD nonce reuse after a restore (RFC 8613 Appendix B.1.1), so give every server its own durable store, or a store that puts a name of the server in front of the context names (and restore with the same one).
sends one request and returns its response.
Constructors
Functions
The sequential flow: message_1 to message_3 (and message_4 when expectMessage4).
The RFC 9668 flow: message_1 and message_2 are exchanged here; message_3 is held back and sent with the first request protected by the returned CombinedHandshake.security.