TokenGenerator

fun interface TokenGenerator(source)

Chooses tokens for new requests (RFC 7252 §5.3.1). The endpoint asks again when a token is already in use towards the same peer, so a generator only needs to make collisions unlikely.

When the token's randomness matters. On a path no security protocol protects (coap, coap+tcp, coap+ws), the token is all an off-path attacker has to guess to have a forged response accepted, so RFC 7252 §5.3.1 asks for at least 32 random bits there. Inside a DTLS session or a TLS connection nobody but the peer can send, and the token's job is to bind each response to the right request, which (D)TLS itself does not do (RFC 9175 §4.1): a token reused on the session could match a late response, or a notification the client no longer wants, to a new request. There a sequence number does it best, which sessionSequence, the default, uses. OSCORE binds a response to its request by itself (RFC 8613 §7.1), whatever the token. A deployment that must draw all its randomness from one approved provider passes its own Random or generator.

Thread safety. An endpoint calls its generator under its own lock, so a generator need not be thread safe, but one that keeps state, such as sessionSequence, must not be shared between endpoints. Leave CoapEndpointConfig.tokenGenerator null and every endpoint creates its own.

Types

Link copied to clipboard
object Companion

Functions

Link copied to clipboard
open fun forget(peer: Endpoint)

peer will never be used again: its DTLS session ended or its connection closed, and a new session or connection to the same peer has new keys. Per-peer state can go.

Link copied to clipboard
abstract fun next(peer: Endpoint): ByteArray

A token of 0 to 8 bytes for a new request to peer.