Internal API functions for interfacing with DTLS libraries. More...

Typedefs
typedef enum coap_dtls_role_t	coap_dtls_role_t

Enumerations
enum	coap_dtls_role_t { COAP_DTLS_ROLE_CLIENT, COAP_DTLS_ROLE_SERVER }

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

int	coap_dtls_context_set_psk (struct coap_context_t coap_context, const char identity_hint, coap_dtls_role_t role)
	Set the DTLS context's default PSK information. More...

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

int	coap_dtls_context_set_pki_root_cas (struct 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 (struct 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 (struct coap_session_t *coap_session)
	Create a new client-side session. More...

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

void	coap_dtls_free_session (struct 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 (struct coap_session_t *coap_session)
	Notify of a change in the CoAP session's MTU, for example after a PMTU update. More...

int	coap_dtls_send (struct 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 (struct coap_session_t *coap_session, coap_tick_t now)
	Get next timeout for this session. More...

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

int	coap_dtls_receive (struct 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 (struct coap_session_t coap_session, const uint8_t data, size_t data_len)
	Handling client HELLO messages from a new candiate peer. More...

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

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

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

void	coap_tls_free_session (struct 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 (struct 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 (struct coap_session_t coap_session, uint8_t data, size_t data_len)
	Read some data from a TLS peer. More...

void	coap_dtls_startup (void)
	Initialize the underlying (D)TLS Library layer. 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 functions for interfacing with DTLS libraries.

Typedef Documentation

◆ coap_dtls_role_t

typedef enum coap_dtls_role_t coap_dtls_role_t

Enumeration Type Documentation

◆ coap_dtls_role_t

enum coap_dtls_role_t

Enumerator
COAP_DTLS_ROLE_CLIENT	Internal function invoked for client.
COAP_DTLS_ROLE_SERVER	Internal function invoked for server.

Definition at line 266 of file coap_dtls.h.

Function Documentation

◆ coap_dtls_context_check_keys_enabled()

int coap_dtls_context_check_keys_enabled ( struct coap_context_t * coap_context )

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

Internal function.

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

int coap_dtls_context_set_pki	(	struct coap_context_t *	coap_context,
		coap_dtls_pki_t *	setup_data,
		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.

Internal function.

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	(	struct 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.

Internal function.

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

int coap_dtls_context_set_psk	(	struct coap_context_t *	coap_context,
		const char *	identity_hint,
		coap_dtls_role_t	role
	)

Set the DTLS context's default PSK information.

This does the PSK specifics following coap_dtls_new_context(). If COAP_DTLS_ROLE_SERVER, then identity hint will also get set. 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.

Internal function.

Parameters

coap_context	The CoAP context.
identity_hint	The default PSK server identity hint sent to a client. Required parameter. If `NULL`, will be set to "". Empty string is a valid hint. This parameter is ignored if COAP_DTLS_ROLE_CLIENT
role	One of `COAP_DTLS_ROLE_CLIENT` or `COAP_DTLS_ROLE_SERVER`

Returns: 1 if successful, else 0.

◆ coap_dtls_free_context()

void coap_dtls_free_context ( void * dtls_context )

Releases the storage allocated for dtls_context.

Internal function.

Parameters

dtls_context The DTLS context as returned by coap_dtls_new_context().

◆ coap_dtls_free_session()

void coap_dtls_free_session ( struct 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.

Internal function.

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.

Internal function.

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 ( struct coap_session_t * coap_session )

Get DTLS overhead over cleartext PDUs.

Internal function.

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	(	struct coap_session_t *	coap_session,
		coap_tick_t	now
	)

Get next timeout for this session.

Internal function.

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

void coap_dtls_handle_timeout ( struct coap_session_t * coap_session )

Handle a DTLS timeout expiration.

Internal function.

Parameters

coap_session The CoAP session.

◆ coap_dtls_hello()

int coap_dtls_hello	(	struct 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.

Internal function.

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.

◆ coap_dtls_is_context_timeout()

int coap_dtls_is_context_timeout ( void )

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

Internal function.

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

Definition at line 114 of file coap_notls.c.

Here is the caller graph for this function:

◆ coap_dtls_new_client_session()

void* coap_dtls_new_client_session ( struct coap_session_t * coap_session )

Create a new client-side session.

This should send a HELLO to the server.

Internal function.

Parameters

coap_session The CoAP session.

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

◆ coap_dtls_new_context()

void* coap_dtls_new_context ( struct 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.

Internal function.

Parameters

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

Returns: A DTLS context object or NULL on error.

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;

Definition at line 167 of file coap_dtls_gnutls.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ coap_dtls_new_server_session()

void* coap_dtls_new_server_session ( struct 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.

Internal function.

Parameters

coap_session The CoAP session.

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

◆ coap_dtls_receive()

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

Handling incoming data from a DTLS peer.

Internal function.

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

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

Send data to a DTLS peer.

Internal function.

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 ( struct coap_session_t * coap_session )

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

Internal function.

Parameters

coap_session The CoAP session.

◆ coap_dtls_startup()

void coap_dtls_startup ( void )

Initialize the underlying (D)TLS Library layer.

Internal function.

Definition at line 70 of file coap_notls.c.

Here is the caller graph for this function:

◆ 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.

Definition at line 592 of file coap_session.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ coap_tls_free_session()

void coap_tls_free_session ( struct 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.

Internal function.

Parameters

coap_session The CoAP session.

◆ coap_tls_new_client_session()

void* coap_tls_new_client_session	(	struct coap_session_t *	coap_session,
		int *	connected
	)

Create a new TLS client-side session.

Internal function.

Parameters

coap_session	The CoAP session.
connected	Updated with whether the connection is connected yet or not. `0` is not connected, `1` is connected.

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

◆ coap_tls_new_server_session()

void* coap_tls_new_server_session	(	struct coap_session_t *	coap_session,
		int *	connected
	)

Create a TLS new server-side session.

Internal function.

Parameters

coap_session	The CoAP session.
connected	Updated with whether the connection is connected yet or not. `0` is not connected, `1` is connected.

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

◆ coap_tls_read()

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

Read some data from a TLS peer.

Internal function.

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	(	struct coap_session_t *	coap_session,
		const uint8_t *	data,
		size_t	data_len
	)

Send data to a TLS peer, with implicit flush.

Internal function.

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.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ coap_dtls_role_t

Enumeration Type Documentation

◆ coap_dtls_role_t

Function Documentation

◆ coap_dtls_context_check_keys_enabled()

◆ coap_dtls_context_set_pki()

◆ coap_dtls_context_set_pki_root_cas()

◆ coap_dtls_context_set_psk()

◆ coap_dtls_free_context()

◆ coap_dtls_free_session()

◆ coap_dtls_get_context_timeout()

◆ coap_dtls_get_overhead()

◆ coap_dtls_get_timeout()

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

◆ coap_session_new_dtls_session()

◆ coap_tls_free_session()

◆ coap_tls_new_client_session()

◆ coap_tls_new_server_session()

◆ coap_tls_read()

◆ coap_tls_write()