Package-level declarations

Types

Link copied to clipboard

An authentication credential, CRED_I or CRED_R (RFC 9528 §3.5.2): the exact CBOR item EDHOC hashes and MACs, together with the authentication public key it carries.

Link copied to clipboard

How one party proves possession of its authentication key (RFC 9528 §3.2, §3.5.1).

Link copied to clipboard

An EDHOC cipher suite, RFC 9528 §3.6 and §10.2 (IANA "EDHOC Cipher Suites").

Link copied to clipboard

An EDHOC connection identifier, C_I or C_R (RFC 9528 §3.3). Connection identifiers are byte strings; on the wire, a one-byte string that equals the one-byte CBOR encoding of an integer in -24..23 is sent as that integer, any other string as a CBOR byte string (RFC 9528 §3.3.2). With OSCORE the bytes become a Recipient ID unchanged (RFC 9528 §3.3.3).

Link copied to clipboard

Chooses the connection identifier an endpoint asks its peer to use (RFC 9528 §3.3.1). The Initiator calls it once per message_1 with peer = null; the Responder calls it with C_I and must not return C_I, because with OSCORE both would become the same Recipient ID (RFC 9528 §3.3.3).

Link copied to clipboard

ID_CRED_I or ID_CRED_R (RFC 9528 §3.5.3): a COSE header map that identifies a credential by reference or carries it by value.

Link copied to clipboard
fun interface CredentialResolver

Turns a received ID_CRED_x into the peer's authentication credential (RFC 9528 §5.3.3 step 5, §5.4.3 step 5). This is where the application decides whom it trusts: return only credentials it is willing to authenticate (RFC 9528 Appendix D).

Link copied to clipboard
interface EadHandler

Produces and consumes External Authorization Data for a security application (RFC 9528 §3.8, Appendix E). Both methods have defaults, so a handler overrides only what it uses.

Link copied to clipboard
class EadItem(val label: Int, value: ByteArray? = null)

One External Authorization Data item, ead = ( ead_label : int, ? ead_value : bstr ) (RFC 9528 §3.8).

Link copied to clipboard
class EdhocError(val code: Int, val info: CborValue)

An EDHOC error message, RFC 9528 §6: the CBOR sequence ( ERR_CODE : int, ERR_INFO : any ).

Link copied to clipboard
open class EdhocException(val error: EdhocError, message: String = error.diagnostic ?: error.toString(), cause: Throwable? = null) : KcoapException

An EDHOC session failed. error is what RFC 9528 §6 says to tell the peer, and errorMessage is that error message encoded, ready to send, or null when nothing may be sent. Like the exceptions of kcoap's other protocols, it is a KcoapException.

Link copied to clipboard
class EdhocInitiator(config: EdhocInitiatorConfig, crypto: CryptoBackend, loggerFactory: LoggerFactory = LoggerFactory.Global)

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.

Link copied to clipboard
class EdhocInitiatorConfig(val method: EdhocMethod, cipherSuites: List<CipherSuite>, credentials: List<LocalCredential>, val credentialResolver: CredentialResolver, val connectionIdentifiers: ConnectionIdentifierProvider = ConnectionIdentifierProvider.Random, val eadHandler: EadHandler = EadHandler.None, val ephemeralKeys: EphemeralKeySource = EphemeralKeySource.Random, val initialCipherSuite: CipherSuite? = null)

The application profile (RFC 9528 §3.9) of an EdhocInitiator.

Link copied to clipboard

The four EDHOC messages that carry EAD fields (RFC 9528 §3.8).

Link copied to clipboard

The EDHOC authentication methods, RFC 9528 §3.2 Table 2. The name reads Initiator, then Responder.

Link copied to clipboard
class EdhocPeerErrorException @JvmOverloads constructor(error: EdhocError, val retryWith: CipherSuite? = null) : EdhocException

The peer sent an EDHOC error message instead of the expected message. No error is sent back (errorMessage is null): error messages are never answered (RFC 9528 §6, §6.1).

Link copied to clipboard

Where an EDHOC state machine stands, with the state names of RFC 9528 Appendix I.

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

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

Link copied to clipboard
class EdhocResponderConfig(methods: Set<EdhocMethod>, cipherSuites: List<CipherSuite>, credentials: List<LocalCredential>, val credentialResolver: CredentialResolver, val connectionIdentifiers: ConnectionIdentifierProvider = ConnectionIdentifierProvider.Random, val eadHandler: EadHandler = EadHandler.None, val ephemeralKeys: EphemeralKeySource = EphemeralKeySource.Random)

The application profile (RFC 9528 §3.9) of an EdhocResponder.

Link copied to clipboard

The two EDHOC roles (RFC 9528 §3.1): the Initiator sends message_1, the Responder answers it.

Link copied to clipboard

The output of a completed EDHOC session (RFC 9528 §4.1.3, §4.2): PRK_out, the EDHOC_Exporter for application keys, EDHOC_KeyUpdate, and what was negotiated and authenticated.

Link copied to clipboard
fun interface EphemeralKeySource

Where ephemeral key pairs come from: fresh ones for every session by default (RFC 9528 §9.2 requires that), or fixed ones to replay the RFC 9529 traces. Called for X (Initiator, Diffie-Hellman and KEM suites) and Y (Responder, Diffie-Hellman suites; a KEM Responder encapsulates instead).

Link copied to clipboard

The EDHOC key exchange algorithm of a cipher suite (RFC 9528 §3.6).

Link copied to clipboard
class LocalCredential(val credential: AuthenticationCredential, val identifier: CredentialIdentifier, val privateKey: PrivateKey, val authentication: AuthenticationKind)

This endpoint's own authentication material: CRED_x, how the peer is told about it (ID_CRED_x), and the handle of the private authentication key, which never leaves its dev.kcoap.crypto.CryptoBackend.

Link copied to clipboard
class Message3

What EdhocInitiator.createMessage3 returns: message_3 to send (RFC 9528 §5.4.2) and the session it completes, so no caller has to read a nullable EdhocInitiator.session.

Link copied to clipboard
class TrustedCredentials(crypto: CryptoBackend, credentials: List<AuthenticationCredential>, certificateValidator: CertificateValidator? = null) : CredentialResolver

A CredentialResolver over a fixed set of trusted credentials: