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)

Enumerations
enum	coap_define_issue_key_t { COAP_DEFINE_KEY_CA , COAP_DEFINE_KEY_ROOT_CA , COAP_DEFINE_KEY_PUBLIC , COAP_DEFINE_KEY_PRIVATE }

enum	coap_define_issue_fail_t { COAP_DEFINE_FAIL_BAD , COAP_DEFINE_FAIL_NOT_SUPPORTED , COAP_DEFINE_FAIL_NONE }

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

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.

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.

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.

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.

int	coap_dtls_context_load_pki_trust_store (coap_context_t *coap_context)
	Load dtls context's default trusted CAs for a client or server.

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.

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

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

void *	coap_dtls_new_server_session (coap_session_t *coap_session)
	Create a new DTLS server-side 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.

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.

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

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

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

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

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

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

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.

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

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

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

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

void *	coap_tls_new_server_session (coap_session_t *coap_session)
	Create a TLS new server-side 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.

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.

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

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

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

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

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

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

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.

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

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

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.

void	coap_dtls_map_key_type_to_define (const coap_dtls_pki_t setup_data, coap_dtls_key_t key)
	Map the PKI key definitions to the new DEFINE format.

int	coap_dtls_define_issue (coap_define_issue_key_t type, coap_define_issue_fail_t fail, coap_dtls_key_t *key, const coap_dtls_role_t role, int ret)
	Report PKI DEFINE type issue.

int	coap_dtls_set_cid_tuple_change (coap_context_t *context, uint8_t every)
	Set the Connection ID client tuple frequency change for testing CIDs.

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

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 43 of file coap_dtls_internal.h.

Enumeration Type Documentation

◆ coap_define_issue_fail_t

enum coap_define_issue_fail_t

Enumerator
COAP_DEFINE_FAIL_BAD
COAP_DEFINE_FAIL_NOT_SUPPORTED
COAP_DEFINE_FAIL_NONE

Definition at line 57 of file coap_dtls_internal.h.

◆ coap_define_issue_key_t

enum coap_define_issue_key_t

Enumerator
COAP_DEFINE_KEY_CA
COAP_DEFINE_KEY_ROOT_CA
COAP_DEFINE_KEY_PUBLIC
COAP_DEFINE_KEY_PRIVATE

Definition at line 50 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 285 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_load_pki_trust_store()

int coap_dtls_context_load_pki_trust_store ( coap_context_t * coap_context )

Load dtls context's default trusted CAs for a client or server.

Parameters

coap_context The current coap_context_t object.

Returns: 1 if successful, 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_lkd().

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_define_issue()

int coap_dtls_define_issue	(	coap_define_issue_key_t	type,
		coap_define_issue_fail_t	fail,
		coap_dtls_key_t *	key,
		const coap_dtls_role_t	role,
		int	ret
	)

Report PKI DEFINE type issue.

Parameters

type	The type of key with the issue.
fail	Why the key is failing.
key	The key with the issue.
role	Whether this is for the Client or Server.
ret	Value to return.

Returns: 0 as there is a failure.

Definition at line 165 of file coap_dtls.c.

Here is the call graph for this function:

◆ 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 266 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 219 of file coap_notls.c.

Here is the caller graph for this function:

◆ coap_dtls_map_key_type_to_define()

void coap_dtls_map_key_type_to_define	(	const coap_dtls_pki_t *	setup_data,
		coap_dtls_key_t *	key
	)

Map the PKI key definitions to the new DEFINE format.

Parameters

setup_data	The PKI definition.
key	Updated with the DEFINE format of the key definitions.

Definition at line 26 of file coap_dtls.c.

◆ 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_set_cid_tuple_change()

int coap_dtls_set_cid_tuple_change	(	coap_context_t *	context,
		uint8_t	every
	)

Set the Connection ID client tuple frequency change for testing CIDs.

Parameters

context	The coap_context_t object.
every	Change the client's source port `every` packets sent.

Returns: 1 if frequency change set (CID supported), else 0.

Here is the caller graph for this function:

◆ coap_dtls_shutdown()

void coap_dtls_shutdown ( void )

Close down the underlying (D)TLS Library layer.

Definition at line 166 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 154 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.

◆ 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 314 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 295 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

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ COAP_DTLS_RETRANSMIT_COAP_TICKS

Enumeration Type Documentation

◆ coap_define_issue_fail_t

◆ coap_define_issue_key_t

Function Documentation

◆ coap_dtls_close()

◆ coap_dtls_context_check_keys_enabled()

◆ coap_dtls_context_load_pki_trust_store()

◆ coap_dtls_context_set_cpsk()

◆ coap_dtls_context_set_pki()

◆ coap_dtls_context_set_pki_root_cas()

◆ coap_dtls_context_set_spsk()

◆ coap_dtls_define_issue()

◆ 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_map_key_type_to_define()

◆ 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_set_cid_tuple_change()

◆ 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()