Internal API for DTLS Support. More...

Collaboration diagram for DTLS Support:

Macros
#define	COAP_DTLS_RETRANSMIT_COAP_TICKS (COAP_DTLS_RETRANSMIT_MS * COAP_TICKS_PER_SECOND / 1000)

Functions
void *	coap_dtls_new_context (coap_context_t *coap_context)
	Creates a new DTLS context for the given `coap_context`. More...

int	coap_dtls_context_set_spsk (coap_context_t coap_context, coap_dtls_spsk_t setup_data)
	Set the DTLS context's default server PSK information. More...

int	coap_dtls_context_set_cpsk (coap_context_t coap_context, coap_dtls_cpsk_t setup_data)
	Set the DTLS context's default client PSK information. More...

int	coap_dtls_context_set_pki (coap_context_t coap_context, const coap_dtls_pki_t setup_data, const coap_dtls_role_t role)
	Set the DTLS context's default server PKI information. More...

int	coap_dtls_context_set_pki_root_cas (coap_context_t coap_context, const char ca_file, const char *ca_dir)
	Set the dtls context's default Root CA information for a client or server. More...

int	coap_dtls_context_check_keys_enabled (coap_context_t *coap_context)
	Check whether one of the coap_dtls_context_set_{psk\|pki}() functions have been called. More...

void	coap_dtls_free_context (void *dtls_context)
	Releases the storage allocated for `dtls_context`. More...

void *	coap_dtls_new_client_session (coap_session_t *coap_session)
	Create a new client-side session. More...

void *	coap_dtls_new_server_session (coap_session_t *coap_session)
	Create a new DTLS server-side session. More...

void	coap_dtls_free_session (coap_session_t *coap_session)
	Terminates the DTLS session (may send an ALERT if necessary) then frees the underlying TLS library object containing security parameters for the session. More...

void	coap_dtls_session_update_mtu (coap_session_t *coap_session)
	Notify of a change in the CoAP session's MTU, for example after a PMTU update. More...

ssize_t	coap_dtls_send (coap_session_t coap_session, const uint8_t data, size_t data_len)
	Send data to a DTLS peer. More...

int	coap_dtls_is_context_timeout (void)
	Check if timeout is handled per CoAP session or per CoAP context. More...

coap_tick_t	coap_dtls_get_context_timeout (void *dtls_context)
	Do all pending retransmits and get next timeout. More...

coap_tick_t	coap_dtls_get_timeout (coap_session_t *coap_session, coap_tick_t now)
	Get next timeout for this session. More...

int	coap_dtls_handle_timeout (coap_session_t *coap_session)
	Handle a DTLS timeout expiration. More...

int	coap_dtls_receive (coap_session_t coap_session, const uint8_t data, size_t data_len)
	Handling incoming data from a DTLS peer. More...

int	coap_dtls_hello (coap_session_t coap_session, const uint8_t data, size_t data_len)
	Handling client HELLO messages from a new candiate peer. More...

void	coap_dtls_establish (coap_session_t *session)
	Layer function interface for layer below DTLS connect being established. More...

void	coap_dtls_close (coap_session_t *session)
	Layer function interface for DTLS close for a session. More...

unsigned int	coap_dtls_get_overhead (coap_session_t *coap_session)
	Get DTLS overhead over cleartext PDUs. More...

void *	coap_tls_new_client_session (coap_session_t *coap_session)
	Create a new TLS client-side session. More...

void *	coap_tls_new_server_session (coap_session_t *coap_session)
	Create a TLS new server-side session. More...

void	coap_tls_free_session (coap_session_t *coap_session)
	Terminates the TLS session (may send an ALERT if necessary) then frees the underlying TLS library object containing security parameters for the session. More...

ssize_t	coap_tls_write (coap_session_t coap_session, const uint8_t data, size_t data_len)
	Send data to a TLS peer, with implicit flush. More...

ssize_t	coap_tls_read (coap_session_t coap_session, uint8_t data, size_t data_len)
	Read some data from a TLS peer. More...

void	coap_tls_establish (coap_session_t *session)
	Layer function interface for layer below TLS accept/connect being established. More...

void	coap_tls_close (coap_session_t *session)
	Layer function interface for TLS close for a session. More...

const coap_bin_const_t *	coap_get_session_client_psk_key (const coap_session_t *coap_session)
	Get the current client's PSK key. More...

const coap_bin_const_t *	coap_get_session_client_psk_identity (const coap_session_t *coap_session)
	Get the current client's PSK identity. More...

const coap_bin_const_t *	coap_get_session_server_psk_key (const coap_session_t *coap_session)
	Get the current server's PSK key. More...

const coap_bin_const_t *	coap_get_session_server_psk_hint (const coap_session_t *coap_session)
	Get the current server's PSK identity hint. More...

void	coap_dtls_startup (void)
	Initialize the underlying (D)TLS Library layer. More...

void	coap_dtls_shutdown (void)
	Close down the underlying (D)TLS Library layer. More...

void *	coap_dtls_get_tls (const coap_session_t session, coap_tls_library_t tls_lib)
	Get the actual (D)TLS object for the session. More...

coap_session_t *	coap_session_new_dtls_session (coap_session_t *session, coap_tick_t now)
	Create a new DTLS session for the `session`. More...

Detailed Description

Internal API for DTLS Support.

Macro Definition Documentation

◆ COAP_DTLS_RETRANSMIT_COAP_TICKS

#define COAP_DTLS_RETRANSMIT_COAP_TICKS (COAP_DTLS_RETRANSMIT_MS * COAP_TICKS_PER_SECOND / 1000)

Definition at line 38 of file coap_dtls_internal.h.

Function Documentation

◆ coap_dtls_close()

void coap_dtls_close ( coap_session_t * session )

Layer function interface for DTLS close for a session.

Parameters

session Session to do the DTLS close on.

Definition at line 40 of file coap_dtls.c.

Here is the call graph for this function:

◆ coap_dtls_context_check_keys_enabled()

int coap_dtls_context_check_keys_enabled ( coap_context_t * coap_context )

Check whether one of the coap_dtls_context_set_{psk|pki}() functions have been called.

Parameters

coap_context The current coap_context_t object.

Returns: 1 if coap_dtls_context_set_{psk|pki}() called, else 0.

◆ coap_dtls_context_set_cpsk()

int coap_dtls_context_set_cpsk	(	coap_context_t *	coap_context,
		coap_dtls_cpsk_t *	setup_data
	)

Set the DTLS context's default client PSK information.

This does the PSK specifics following coap_dtls_new_context().

Parameters

coap_context	The CoAP context.
setup_data	A structure containing setup data originally passed into coap_new_client_session_psk2().

Returns: 1 if successful, else 0.

◆ coap_dtls_context_set_pki()

int coap_dtls_context_set_pki	(	coap_context_t *	coap_context,
		const coap_dtls_pki_t *	setup_data,
		const coap_dtls_role_t	role
	)

Set the DTLS context's default server PKI information.

This does the PKI specifics following coap_dtls_new_context(). If COAP_DTLS_ROLE_SERVER, then the information will get put into the TLS library's context (from which sessions are derived). If COAP_DTLS_ROLE_CLIENT, then the information will get put into the TLS library's session.

Parameters

coap_context	The CoAP context.
setup_data	Setup information defining how PKI is to be setup. Required parameter. If `NULL`, PKI will not be set up.
role	One of `COAP_DTLS_ROLE_CLIENT` or `COAP_DTLS_ROLE_SERVER`

Returns: 1 if successful, else 0.

◆ coap_dtls_context_set_pki_root_cas()

int coap_dtls_context_set_pki_root_cas	(	coap_context_t *	coap_context,
		const char *	ca_file,
		const char *	ca_dir
	)

Set the dtls context's default Root CA information for a client or server.

Parameters

coap_context	The current coap_context_t object.
ca_file	If not `NULL`, is the full path name of a PEM encoded file containing all the Root CAs to be used.
ca_dir	If not `NULL`, points to a directory containing PEM encoded files containing all the Root CAs to be used.

Returns: 1 if successful, else 0.

◆ coap_dtls_context_set_spsk()

int coap_dtls_context_set_spsk	(	coap_context_t *	coap_context,
		coap_dtls_spsk_t *	setup_data
	)

Set the DTLS context's default server PSK information.

This does the PSK specifics following coap_dtls_new_context().

Parameters

coap_context	The CoAP context.
setup_data	A structure containing setup data originally passed into coap_context_set_psk2().

Returns: 1 if successful, else 0.

◆ coap_dtls_establish()

void coap_dtls_establish ( coap_session_t * session )

Layer function interface for layer below DTLS connect being established.

If this layer is properly established on invocation, then the next layer must get called by calling session->lfunc[COAP_LAYER_TLS].establish(session) (or done at any point when DTLS is established).

Parameters

session Session that the lower layer connect was done on.

Definition at line 21 of file coap_dtls.c.

Here is the call graph for this function:

◆ coap_dtls_free_context()

void coap_dtls_free_context ( void * dtls_context )

Releases the storage allocated for dtls_context.

Parameters

dtls_context The DTLS context as returned by coap_dtls_new_context().

◆ coap_dtls_free_session()

void coap_dtls_free_session ( coap_session_t * coap_session )

Terminates the DTLS session (may send an ALERT if necessary) then frees the underlying TLS library object containing security parameters for the session.

Parameters

coap_session The CoAP session.

◆ coap_dtls_get_context_timeout()

coap_tick_t coap_dtls_get_context_timeout ( void * dtls_context )

Do all pending retransmits and get next timeout.

Parameters

dtls_context The DTLS context.

Returns: 0 if no event is pending or date of the next retransmit.

◆ coap_dtls_get_overhead()

unsigned int coap_dtls_get_overhead ( coap_session_t * coap_session )

Get DTLS overhead over cleartext PDUs.

Parameters

coap_session The CoAP session.

Returns: Maximum number of bytes added by DTLS layer.

◆ coap_dtls_get_timeout()

coap_tick_t coap_dtls_get_timeout	(	coap_session_t *	coap_session,
		coap_tick_t	now
	)

Get next timeout for this session.

Parameters

coap_session	The CoAP session.
now	The current time in ticks.

Returns: 0 If no event is pending or ticks time of the next retransmit.

◆ coap_dtls_get_tls()

void * coap_dtls_get_tls	(	const coap_session_t *	session,
		coap_tls_library_t *	tls_lib
	)

Get the actual (D)TLS object for the session.

Parameters

session	The session.
tls_lib	Updated with the library type.

Returns: The TLS information.

◆ coap_dtls_handle_timeout()

int coap_dtls_handle_timeout ( coap_session_t * coap_session )

Handle a DTLS timeout expiration.

Parameters

coap_session The CoAP session.

Returns: 1 timed out or 0 still timing out

◆ coap_dtls_hello()

int coap_dtls_hello	(	coap_session_t *	coap_session,
		const uint8_t *	data,
		size_t	data_len
	)

Handling client HELLO messages from a new candiate peer.

Note that session->tls is empty.

Parameters

coap_session	The CoAP session.
data	Encrypted datagram.
data_len	Encrypted datagram size.

Returns: 0 if a cookie verification message has been sent, 1 if the HELLO contains a valid cookie and a server session should be created, -1 if the message is invalid.

Here is the caller graph for this function:

◆ coap_dtls_is_context_timeout()

int coap_dtls_is_context_timeout ( void )

Check if timeout is handled per CoAP session or per CoAP context.

Returns: 1 of timeout and retransmit is per context, 0 if it is per session.

Definition at line 183 of file coap_notls.c.

Here is the caller graph for this function:

◆ coap_dtls_new_client_session()

void * coap_dtls_new_client_session ( coap_session_t * coap_session )

Create a new client-side session.

This should send a HELLO to the server.

Parameters

coap_session The CoAP session.

Returns: Opaque handle to underlying TLS library object containing security parameters for the session.

Here is the caller graph for this function:

◆ coap_dtls_new_context()

void * coap_dtls_new_context ( coap_context_t * coap_context )

Creates a new DTLS context for the given coap_context.

This function returns a pointer to a new DTLS context object or NULL on error.

Parameters

coap_context The CoAP context where the DTLS object shall be used.

Returns: A DTLS context object or NULL on error.

◆ coap_dtls_new_server_session()

void * coap_dtls_new_server_session ( coap_session_t * coap_session )

Create a new DTLS server-side session.

Called after coap_dtls_hello() has returned 1, signalling that a validated HELLO was received from a client. This should send a HELLO to the server.

Parameters

coap_session The CoAP session.

Returns: Opaque handle to underlying TLS library object containing security parameters for the DTLS session.

Here is the caller graph for this function:

◆ coap_dtls_receive()

int coap_dtls_receive	(	coap_session_t *	coap_session,
		const uint8_t *	data,
		size_t	data_len
	)

Handling incoming data from a DTLS peer.

Parameters

coap_session	The CoAP session.
data	Encrypted datagram.
data_len	Encrypted datagram size.

Returns: Result of coap_handle_dgram on the decrypted CoAP PDU or -1 for error.

◆ coap_dtls_send()

ssize_t coap_dtls_send	(	coap_session_t *	coap_session,
		const uint8_t *	data,
		size_t	data_len
	)

Send data to a DTLS peer.

Parameters

coap_session	The CoAP session.
data	pointer to data.
data_len	Number of bytes to send.

Returns: 0 if this would be blocking, -1 if there is an error or the number of cleartext bytes sent.

◆ coap_dtls_session_update_mtu()

void coap_dtls_session_update_mtu ( coap_session_t * coap_session )

Notify of a change in the CoAP session's MTU, for example after a PMTU update.

Parameters

coap_session The CoAP session.

◆ coap_dtls_shutdown()

void coap_dtls_shutdown ( void )

Close down the underlying (D)TLS Library layer.

Definition at line 130 of file coap_notls.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ coap_dtls_startup()

void coap_dtls_startup ( void )

Initialize the underlying (D)TLS Library layer.

Definition at line 118 of file coap_notls.c.

Here is the caller graph for this function:

◆ coap_get_session_client_psk_identity()

const coap_bin_const_t * coap_get_session_client_psk_identity ( const coap_session_t * coap_session )

Get the current client's PSK identity.

Parameters

coap_session The CoAP session.

Returns: NULL if no identity, else a pointer the current identity.

Definition at line 285 of file coap_net.c.

◆ coap_get_session_client_psk_key()

const coap_bin_const_t * coap_get_session_client_psk_key ( const coap_session_t * coap_session )

Get the current client's PSK key.

Parameters

coap_session The CoAP session.

Returns: NULL if no key, else a pointer the current key.

◆ coap_get_session_server_psk_hint()

const coap_bin_const_t * coap_get_session_server_psk_hint ( const coap_session_t * coap_session )

Get the current server's PSK identity hint.

Parameters

coap_session The CoAP session.

Returns: NULL if no hint, else a pointer the current hint.

◆ coap_get_session_server_psk_key()

const coap_bin_const_t * coap_get_session_server_psk_key ( const coap_session_t * coap_session )

Get the current server's PSK key.

Parameters

coap_session The CoAP session.

Returns: NULL if no key, else a pointer the current key.

◆ coap_session_new_dtls_session()

coap_session_t * coap_session_new_dtls_session	(	coap_session_t *	session,
		coap_tick_t	now
	)

Create a new DTLS session for the session.

Note: the session is released if no DTLS server session can be created.

Parameters

session	Session to add DTLS session to
now	The current time in ticks.

Returns: CoAP session or NULL if error.

◆ coap_tls_close()

void coap_tls_close ( coap_session_t * session )

Layer function interface for TLS close for a session.

Parameters

session Session to do the TLS close on.

Definition at line 69 of file coap_dtls.c.

Here is the call graph for this function:

◆ coap_tls_establish()

void coap_tls_establish ( coap_session_t * session )

Layer function interface for layer below TLS accept/connect being established.

This function initiates an accept/connect at the TLS layer.

If this layer is properly established on invocation, then the next layer must get called by calling session->lfunc[COAP_LAYER_TLS].establish(session) (or done at any point when TLS is established).

Parameters

session Session that the lower layer accept/connect was done on.

Definition at line 50 of file coap_dtls.c.

Here is the call graph for this function:

◆ coap_tls_free_session()

void coap_tls_free_session ( coap_session_t * coap_session )

Terminates the TLS session (may send an ALERT if necessary) then frees the underlying TLS library object containing security parameters for the session.

Parameters

coap_session The CoAP session.

◆ coap_tls_new_client_session()

void * coap_tls_new_client_session ( coap_session_t * coap_session )

Create a new TLS client-side session.

Parameters

coap_session The CoAP session.

Returns: Opaque handle to underlying TLS library object containing security parameters for the session.

Here is the caller graph for this function:

◆ coap_tls_new_server_session()

void * coap_tls_new_server_session ( coap_session_t * coap_session )

Create a TLS new server-side session.

Parameters

coap_session The CoAP session.

Returns: Opaque handle to underlying TLS library object containing security parameters for the session.

Here is the caller graph for this function:

◆ coap_tls_read()

ssize_t coap_tls_read	(	coap_session_t *	coap_session,
		uint8_t *	data,
		size_t	data_len
	)

Read some data from a TLS peer.

Parameters

coap_session	The CoAP session.
data	Pointer to data.
data_len	Maximum number of bytes to read.

Returns: 0 if this should be retried, -1 if there is an error or the number of cleartext bytes read.

◆ coap_tls_write()

ssize_t coap_tls_write	(	coap_session_t *	coap_session,
		const uint8_t *	data,
		size_t	data_len
	)

Send data to a TLS peer, with implicit flush.

Parameters

coap_session	The CoAP session.
data	Pointer to data.
data_len	Number of bytes to send.

Returns: 0 if this should be retried, -1 if there is an error or the number of cleartext bytes sent.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ COAP_DTLS_RETRANSMIT_COAP_TICKS

Function Documentation

◆ coap_dtls_close()

◆ coap_dtls_context_check_keys_enabled()

◆ coap_dtls_context_set_cpsk()

◆ coap_dtls_context_set_pki()

◆ coap_dtls_context_set_pki_root_cas()

◆ coap_dtls_context_set_spsk()

◆ coap_dtls_establish()

◆ coap_dtls_free_context()

◆ coap_dtls_free_session()

◆ coap_dtls_get_context_timeout()

◆ coap_dtls_get_overhead()

◆ coap_dtls_get_timeout()

◆ coap_dtls_get_tls()

◆ coap_dtls_handle_timeout()

◆ coap_dtls_hello()

◆ coap_dtls_is_context_timeout()

◆ coap_dtls_new_client_session()

◆ coap_dtls_new_context()

◆ coap_dtls_new_server_session()

◆ coap_dtls_receive()

◆ coap_dtls_send()

◆ coap_dtls_session_update_mtu()

◆ coap_dtls_shutdown()

◆ coap_dtls_startup()

◆ coap_get_session_client_psk_identity()

◆ coap_get_session_client_psk_key()

◆ coap_get_session_server_psk_hint()

◆ coap_get_session_server_psk_key()

◆ coap_session_new_dtls_session()

◆ coap_tls_close()

◆ coap_tls_establish()

◆ coap_tls_free_session()

◆ coap_tls_new_client_session()

◆ coap_tls_new_server_session()

◆ coap_tls_read()

◆ coap_tls_write()