EdhocServer

class EdhocServer(config: EdhocResponderConfig, crypto: CryptoBackend, contexts: MutableSecurityContextRepository, sendMessage4: Boolean = false, maxPendingSessions: Int = 64, maxPendingSessionsPerPeer: Int = 8, pendingSessionLifetime: Duration = TransmissionParameters.Default.maxTransmitWait, pendingSessionGracePeriod: Duration = 10.seconds, sequenceStore: SequenceNumberStore? = null, timeSource: TimeSource = TimeSource.Monotonic, listener: EdhocSessionListener = EdhocSessionListener { _, _ -> }, eventListener: EdhocServerEventListener = EdhocServerEventListener.None, loggerFactory: LoggerFactory = LoggerFactory.Global)(source)

The server (EDHOC Responder) side of EDHOC over CoAP: runs one EdhocResponder per session, keyed by the C_R it chose, and turns every completed session into an OSCORE context in contexts.

  • handle is the logic of the EDHOC resource (RFC 9528 Appendix A.2): message_1 starts a session and gets message_2, message_3 completes it (with message_4 when sendMessage4 is set). EdhocResource mounts it in a CoAP server.

  • completeCombined completes a session from the message_3 of an EDHOC + OSCORE request (RFC 9668), for CombinedRequestServer.

contexts is any MutableSecurityContextRepository, usually the one the server's OscoreServer finds contexts in. Contexts from EDHOC accumulate there, one per completed handshake, and this server never removes them: a production server gives it a repository with a bound, which costs an evicted client only a new handshake (its requests then get OSCORE's 4.01 or 4.00, as MutableSecurityContextRepository explains). The default InMemoryContextRepository has none.

A session is established all or nothing: when deriving its context, adding it to contexts or telling listener fails or is cancelled, the context is taken out of contexts again, the session's secrets are wiped (RFC 9528 §9.8), and the client gets an EDHOC error, so neither side keeps a context of a handshake that failed. A failure of this side, such as a repository that throws, is answered with "EDHOC failed" in a 5.00 response (RFC 9528 Appendix A.2.3), its cause logged.

C_R is chosen as RFC 9668 §4.1.2 requires: unused by other sessions, different from C_I, and not the Recipient ID of a context in contexts. It is reserved in the same locked step that checks it, before message_2 is composed, and stays reserved until the session's OSCORE context is in contexts, so concurrent handshakes of this server never share a C_R or collide with a context it is adding. The context is added only if its Recipient ID is still free (MutableSecurityContextRepository.addIfAbsent): when another writer of contexts, such as a second EdhocServer for another application profile (RFC 9668 §5) or the application, took it meanwhile, the handshake fails with an EDHOC error instead of replacing that context.

Until message_3 is verified, nothing about the client is authenticated, so the state it can make the server keep is bounded (RFC 9528 §9.7):

  • A session waits for message_3 only from the peer that sent message_1. A message_3, an error message or an EDHOC + OSCORE request from any other peer is answered as for an unknown C_R, costs no cryptography and leaves the session waiting. Only this unauthenticated state is bound to the peer's address; OSCORE contexts are not.

  • At most maxPendingSessions sessions are in progress, at most maxPendingSessionsPerPeer of them for one peer. A peer is its address and port (for DTLS, its session), so a host sending from many ports counts as many peers. A message_1 beyond the per-peer bound is refused before any processing, with an EDHOC error in a 5.00 response, and reported as EdhocServerEvent.LimitReached.

  • When all maxPendingSessions places are taken, the session that has waited longest for message_3 is dropped for the new one if it has waited longer than pendingSessionGracePeriod, its secrets wiped and EdhocServerEvent.SessionEvicted reported. Only when no session has waited that long is the new one refused as above. A client whose message_3 arrives within the grace period is never evicted.

  • A session that has not received message_3 within pendingSessionLifetime expires; its secrets are wiped and EdhocServerEvent.SessionExpired reported.

These bounds do not stop a flood of message_1 from spoofed addresses: each costs a key generation, a Diffie-Hellman and a signature, and maxPendingSessions of them per pendingSessionGracePeriod (6.4 per second by default) keep new clients out while the flood lasts. That takes an Echo reachability check before message_2 (RFC 9528 Appendix A.2, RFC 9175), which belongs to the CoAP server.

The cipher suites config names are narrowed once to those crypto runs, on first use, and the answer is kept with config for every later session (docs/adr/0001-crypto-capabilities.md).

Parameters

contexts

where the OSCORE context of every completed session goes, and where C_R is checked against the Recipient IDs in use.

pendingSessionLifetime

how long a session waits for message_3: by default MAX_TRANSMIT_WAIT (93 s, RFC 7252 §4.8.2), about as long as a client retransmits message_3 and waits for its answer.

pendingSessionGracePeriod

how long a session waiting for message_3 is safe from eviction: by default 10 s, a round trip and the client's processing of message_2 with time to spare. Give it at least pendingSessionLifetime to never evict, so a full server only refuses.

sequenceStore

holds the Sender Sequence Numbers of the contexts this server derives, under their names "sid=C_I,rid=C_R" (dev.kcoap.oscore.SecurityContextParameters.name). 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 contexts after a restart, as oscoreParameters describes. A name is unique only among the contexts in contexts, so do not share a durable store with contexts kept anywhere else.

listener

told of every session that completes, with its context.

eventListener

receives the EdhocServerEvents.

loggerFactory

where the server's logger comes from, under LogTags.EDHOC.

Constructors

Link copied to clipboard
constructor(config: EdhocResponderConfig, crypto: CryptoBackend, contexts: MutableSecurityContextRepository, sendMessage4: Boolean = false, maxPendingSessions: Int = 64, maxPendingSessionsPerPeer: Int = 8, pendingSessionLifetime: Duration = TransmissionParameters.Default.maxTransmitWait, pendingSessionGracePeriod: Duration = 10.seconds, sequenceStore: SequenceNumberStore? = null, timeSource: TimeSource = TimeSource.Monotonic, listener: EdhocSessionListener = EdhocSessionListener { _, _ -> }, eventListener: EdhocServerEventListener = EdhocServerEventListener.None, loggerFactory: LoggerFactory = LoggerFactory.Global)

Functions

Link copied to clipboard
suspend fun completeCombined(responderId: ConnectionIdentifier, message3: ByteArray, peer: Endpoint): SecurityContext

Processes the message_3 of an RFC 9668 EDHOC + OSCORE request from peer for the session responderId (the 'kid' of the request) and returns the new OSCORE context.

Link copied to clipboard
suspend fun handle(payload: ByteArray, peer: Endpoint): CoapResponse

Answers a POST from peer to the EDHOC resource whose body is payload (RFC 9528 Appendix A.2.1): a 2.04 with message_2 for true, message_1, a 2.04 with message_4 or without payload for C_R, message_3, and a 2.04 for C_R, error message, which ends the session.

Link copied to clipboard
suspend fun pendingSessions(): Int

Sessions waiting for message_3, after dropping the expired ones.