EdhocResponder

class EdhocResponder(config: EdhocResponderConfig, crypto: CryptoBackend, loggerFactory: LoggerFactory = LoggerFactory.Global)(source)

The EDHOC Responder (RFC 9528 §5), as a sans-IO state machine for one session.

val responder = EdhocResponder(config, crypto)
responder.processMessage1(message1) // throws EdhocException, e.g. error code 2 with SUITES_R
transport.reply(responder.createMessage2())
val session = responder.processMessage3(transport.receive())
transport.reply(responder.createMessage4()) // only if the application profile uses message_4

Only the configured suites that crypto runs for the received method are accepted and named in SUITES_R (CipherSuite.isSupportedBy), and a selected suite it cannot run is answered with error code 2 and the suites it can (RFC 9528 §6.3). The configuration asks the backend once and remembers the answers, so message_1 makes no backend probe, also on a backend that does not memoize its own answers. EdhocResponderConfig.supportedBy makes the same choice up front.

Every failure is an EdhocException whose EdhocException.errorMessage, when not null, is the error message to send to the Initiator; the state machine is then EdhocPhase.ABORTED. After processMessage1 the application can inspect method, cipherSuite and peerConnectionIdentifier before answering.

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.

Constructors

Link copied to clipboard
constructor(config: EdhocResponderConfig, crypto: CryptoBackend, loggerFactory: LoggerFactory = LoggerFactory.Global)

Properties

Link copied to clipboard

The selected cipher suite of the accepted message_1.

Link copied to clipboard

Why the state machine aborted, or null.

Link copied to clipboard

METHOD of the accepted message_1.

Link copied to clipboard

C_I of the accepted message_1.

Link copied to clipboard

Where the handshake stands.

Link copied to clipboard

The session, once message_3 has been verified.

Functions

Link copied to clipboard
fun abort(diagnostic: String): ByteArray?

Aborts the session on the application's initiative, for example when C_I or EAD_1 is not acceptable. Returns the error message to send (code 1 with diagnostic) if a received message is waiting for an answer, otherwise null.

Link copied to clipboard
suspend fun createMessage2(): ByteArray

Composes message_2 (RFC 9528 §5.3.2): completes the ephemeral exchange (ECDH, or KEM encapsulation), chooses C_R, and authenticates with MAC_2 and Signature_or_MAC_2.

Link copied to clipboard
suspend fun createMessage4(): ByteArray

Composes message_4 (RFC 9528 §5.5.2), for application profiles that use it: it gives the Initiator key confirmation when no protected application message flows from the Responder (RFC 9528 §5.5).

Link copied to clipboard
suspend fun processMessage1(message1: ByteArray)

Processes message_1 (RFC 9528 §5.2.3): checks the method, the cipher suite negotiation of §6.3 and G_X, and hands EAD_1 to the EadHandler. Supported suites are those configured for the method that the crypto backend runs. A selected suite that is not supported, or preceded in SUITES_I by a supported one, fails with error code 2 and a SUITES_R of supported suites.

Link copied to clipboard
suspend fun processMessage3(message3: ByteArray): EdhocSession

Processes message_3 (RFC 9528 §5.4.3): decrypts PLAINTEXT_3, hands EAD_3 to the EadHandler, resolves ID_CRED_I and verifies Signature_or_MAC_3. On success the state machine is EdhocPhase.COMPLETED and returns the session, which session returns afterwards too.