EdhocSession

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.

The Initiator gets its session after creating message_3, the Responder after verifying it. RFC 9528 §5.4.2 advises the Initiator not to persist the keys until message_4 or a protected message from the Responder has been verified.

Not thread-safe: keyUpdate replaces the keys in place, so callers serialize access. toString() never shows key material.

After destroy, every call that reads or derives key material throws IllegalStateException: the wiped keys would otherwise derive predictable OSCORE secrets.

Types

Link copied to clipboard
object Companion

Properties

Link copied to clipboard

The selected cipher suite; its application algorithms are what OSCORE uses.

Link copied to clipboard

C_I, chosen by the Initiator.

Link copied to clipboard

The authentication method of the session.

Link copied to clipboard

The connection identifier this endpoint chose, which with OSCORE is its Recipient ID (RFC 9528 §3.3.3).

Link copied to clipboard

The connection identifier the peer chose, which with OSCORE is this endpoint's Sender ID.

Link copied to clipboard

The peer's credential, which the session authenticated.

Link copied to clipboard

The peer's ID_CRED_x as received.

Link copied to clipboard

C_R, chosen by the Responder.

Link copied to clipboard

This endpoint's role.

Functions

Link copied to clipboard
fun destroy()

Wipes PRK_out and PRK_exporter. Every call that reads or derives keys throws afterwards; calling this again does nothing.

Link copied to clipboard
suspend fun exporter(label: Int, context: ByteArray, length: Int): ByteArray

EDHOC_Exporter( exporter_label, context, length ) = EDHOC_KDF( PRK_exporter, exporter_label, context, length ) (RFC 9528 §4.2.1). Each (label, context) pair must serve a single purpose.

Link copied to clipboard
suspend fun keyUpdate(context: ByteArray)

EDHOC_KeyUpdate (RFC 9528 Appendix H): PRK_out becomes EDHOC_KDF( PRK_out, 11, context, hash_length ) and PRK_exporter is derived anew. The old keys are wiped, which is what gives forward secrecy; keys already exported from them are the caller's to delete. Both parties must use the same context.

Link copied to clipboard
suspend fun oscoreMasterSalt(length: Int = DEFAULT_OSCORE_SALT_LENGTH): ByteArray

The OSCORE Master Salt, EDHOC_Exporter( 1, h'', oscore_salt_length ), 8 bytes by default (RFC 9528 Appendix A.1).

Link copied to clipboard
suspend fun oscoreMasterSecret(length: Int = cipherSuite.appAead.keyLength): ByteArray

The OSCORE Master Secret, EDHOC_Exporter( 0, h'', oscore_key_length ) (RFC 9528 Appendix A.1). The default length is the key length of the application AEAD.

Link copied to clipboard

A copy of PRK_exporter = EDHOC_KDF( PRK_out, 10, h'', hash_length ) (RFC 9528 §4.1.3). Secret.

Link copied to clipboard

A copy of PRK_out, the session key (RFC 9528 §4.1.3). Secret: store it only where keys belong.

Link copied to clipboard
open override fun toString(): String