EdhocInitiator
The EDHOC Initiator (RFC 9528 §5), as a sans-IO state machine: it takes and returns message bytes and leaves transport, correlation and deduplication (RFC 9528 §3.4, §7) to the caller.
val initiator = EdhocInitiator(config, crypto)
val reply = transport.exchange(initiator.createMessage1())
initiator.processMessage2(reply) // throws EdhocException
val (message3, session) = initiator.createMessage3()
transport.send(message3) // session: PRK_out, exporter, peer credential
initiator.processMessage4(transport.receive()) // only if the application profile uses message_4Only the configured suites that crypto runs for the method are offered (CipherSuite.isSupportedBy), and SUITES_I is a prefix of those suites. The configuration asks the backend once, in the first createMessage1 or in EdhocInitiatorConfig.supportedBy, which makes the same choice up front, and remembers the answers for the sessions after it.
Every failure is an EdhocException; its EdhocException.errorMessage, when not null, is the error message to send to the Responder, and the state machine is then EdhocPhase.ABORTED. One exception is cipher suite negotiation (RFC 9528 §6.3): when the Responder answers message_1 with error code 2 and names a suite this Initiator prefers and runs, processMessage2 throws an EdhocPeerErrorException whose EdhocPeerErrorException.retryWith is that suite, and the Initiator is back at EdhocPhase.START, so createMessage1 can be called again:
try {
initiator.processMessage2(reply)
} catch (e: EdhocPeerErrorException) {
if (e.retryWith == null) throw e
reply = transport.exchange(initiator.createMessage1()) // SUITES_I now ends with e.retryWith
}The four steps list KcoapException, the root of EdhocException, and CancellationException in @Throws, so on Apple platforms Swift catches an EDHOC failure as an NSError, with the Kotlin exception in its userInfo under "KotlinException"; a call out of order is a mistake of the caller and is not listed.
Calling a method out of order throws IllegalStateException and leaves the state unchanged. Instances are not thread-safe; drive one from a single coroutine at a time.
Constructors
Properties
The suite selected for the current or next message_1. Until the first createMessage1 asks the crypto backend, this is the configured choice; that call replaces a default the backend cannot run with the most preferred suite it can.
Why the state machine aborted, or null.
The authenticated Responder credential, once message_2 has been verified.
Where the handshake stands.
The session, once message_3 has been created.
Functions
Aborts the session on the application's initiative, for example when ID_CRED_R or EAD_2 is not acceptable after all. Returns the error message to send (code 1 with diagnostic) if a received message_2 is waiting for an answer, otherwise null.
Composes message_1 (RFC 9528 §5.2.2): SUITES_I up to the selected suite, a fresh ephemeral key pair, and C_I. SUITES_I holds only suites the crypto backend runs for the method, which the configuration knows after asking the backend once; the first call fails with an EdhocException naming what is missing when no suite with a credential, or not the configured initial suite, is among them.
Composes message_3 (RFC 9528 §5.4.2) and completes the session, which comes with it; session returns the same session afterwards.
Processes message_2 (RFC 9528 §5.3.3): decrypts PLAINTEXT_2, hands EAD_2 to the EadHandler, resolves ID_CRED_R through the CredentialResolver and verifies Signature_or_MAC_2.
Processes message_4 (RFC 9528 §5.5.3), which confirms that the Responder derived the same PRK_out. Only valid after createMessage3, and only in application profiles that use message_4.