Package-level declarations

Types

Link copied to clipboard

What EdhocClientHandshake.runCombined returns (RFC 9668 §3.2): the established session and the security whose first protected request carries message_3. Destructure it, or install security for the server with PeerSecurity.install:

Link copied to clipboard

The client side of the EDHOC + OSCORE request (RFC 9668 §3.2): the first request protected with the new OSCORE context also carries EDHOC message_3, saving a round trip. Later requests are plain OSCORE.

Link copied to clipboard

The server side of the EDHOC + OSCORE request (RFC 9668 §3.3), a decorator of the server's OSCORE layer: a request with the EDHOC option has its message_3 split off and processed by edhoc, which adds the new OSCORE context to its repository, and the rest is verified by oscore as an ordinary OSCORE request. Requests without the EDHOC option go to oscore directly.

Link copied to clipboard
class EdhocClientHandshake(config: EdhocInitiatorConfig, crypto: CryptoBackend, server: CoapUri, path: String = EdhocOverCoap.WELL_KNOWN_PATH, loggerFactory: LoggerFactory = LoggerFactory.Global, sequenceStore: SequenceNumberStore? = null, exchange: suspend (CoapRequest) -> CoapResponse)

The client (EDHOC Initiator) side of EDHOC over CoAP, forward message flow (RFC 9528 Appendix A.2.1).

Link copied to clipboard
class EdhocIdentity(val oscore: OscoreIdentity, val peerCredential: AuthenticationCredential, val peerCredentialIdentifier: CredentialIdentifier) : SecurityIdentity

The peer behind the requests an OSCORE context verifies when an EDHOC session established that context (RFC 9528 Appendix A.1): the authentication credential EDHOC verified for the peer, and the context's OSCORE identity. oscoreContext attaches it to the context it derives (dev.kcoap.oscore.SecurityContext.identity), so EdhocServer's contexts carry it, and resource handlers and access policies see it as the request's securityIdentity (ADR 0008).

Link copied to clipboard
class EdhocOscoreSession(val edhoc: EdhocSession, val oscore: SecurityContext)

An established EDHOC session and the OSCORE context derived from it (RFC 9528 Appendix A.1), as EdhocClientHandshake returns them.

Link copied to clipboard

How EDHOC messages travel in CoAP messages (RFC 9528 Appendix A.2, forward message flow): POST requests to /.well-known/edhoc and 2.04 responses. Requests are prefixed so the server can correlate them: message_1 with the CBOR value true, later messages with the server's C_R.

Link copied to clipboard
class EdhocResource(edhoc: EdhocServer, name: String = "edhoc") : CoapResource

The EDHOC resource of a CoAP server (RFC 9528 Appendix A.2): POST requests are handed to edhoc. Mount it under .well-known for the default path:

Link copied to clipboard
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)

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.

Link copied to clipboard
sealed interface EdhocServerEvent

Something an EdhocServer did to a handshake that is not complete yet, for metrics and diagnostics, like the CoAP endpoint's EndpointEvent. The events cover what the server refuses or drops to bound the state unauthenticated clients can make it keep (RFC 9528 §9.7); completed sessions go to EdhocSessionListener.

Link copied to clipboard

Receives the EdhocServerEvents of an EdhocServer. Called outside the server's locks; keep it short.

Link copied to clipboard
fun interface EdhocSessionListener

Called by an EdhocServer when an EDHOC session completes and its OSCORE context is in the server's repository (RFC 9528 Appendix A.1). Pending sessions it refused or dropped go to EdhocServerEventListener.

Link copied to clipboard
class EdhocTransferException(message: String, val response: CoapResponse? = null) : EdhocException

An EDHOC handshake over CoAP failed in the transfer, not in EDHOC itself: the server answered a request to its EDHOC resource with something that is neither a 2.04 nor an EDHOC error response (RFC 9528 Appendix A.2), such as a 4.04 from a server without one, or the peers could not agree on a cipher suite within a few rounds of RFC 9528 §6.3.

Link copied to clipboard
class PeerSecurity(unprotectedPaths: Set<String> = setOf("/${EdhocOverCoap.WELL_KNOWN_PATH}"), allowUnprotected: Boolean = false) : ClientMessageSecurity

Client-side message security chosen per server: a CoapClient is created with one PeerSecurity, and a protection is installed for a server once a handshake with it completes. Requests to the EDHOC resource (unprotectedPaths) go out unprotected.

Functions

Link copied to clipboard
suspend fun EdhocSession.oscoreContext(crypto: CryptoBackend, sequenceStore: SequenceNumberStore = EphemeralSequenceNumberStore(), keyLength: Int = cipherSuite.appAead.keyLength, saltLength: Int = DEFAULT_SALT_LENGTH): SecurityContext

Derives the OSCORE security context of this EDHOC session (RFC 9528 Appendix A.1).

Link copied to clipboard
suspend fun EdhocSession.oscoreParameters(keyLength: Int = cipherSuite.appAead.keyLength, saltLength: Int = DEFAULT_SALT_LENGTH): SecurityContextParameters

The OSCORE security context parameters an EDHOC session establishes (RFC 9528 Appendix A.1):