libcoap  4.2.1
DTLS Support (Internal)

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_tcoap_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

Enumeration Type Documentation

◆ 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_contextThe 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_contextThe CoAP context.
setup_dataSetup information defining how PKI is to be setup. Required parameter. If NULL, PKI will not be set up.
roleOne 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_contextThe current coap_context_t object.
ca_fileIf not NULL, is the full path name of a PEM encoded file containing all the Root CAs to be used.
ca_dirIf 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_contextThe CoAP context.
identity_hintThe 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
roleOne 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_contextThe 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_sessionThe 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_contextThe 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_sessionThe 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_sessionThe CoAP session.
nowThe 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_sessionThe 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_sessionThe CoAP session.
dataEncrypted datagram.
data_lenEncrypted 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_sessionThe 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_contextThe 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_contextThe 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_sessionThe 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_sessionThe CoAP session.
dataEncrypted datagram.
data_lenEncrypted 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_sessionThe CoAP session.
datapointer to data.
data_lenNumber 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_sessionThe 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
sessionSession to add DTLS session to
nowThe 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_sessionThe 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_sessionThe CoAP session.
connectedUpdated 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_sessionThe CoAP session.
connectedUpdated 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_sessionThe CoAP session.
dataPointer to data.
data_lenMaximum 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_sessionThe CoAP session.
dataPointer to data.
data_lenNumber of bytes to send.
Returns
0 if this should be retried, -1 if there is an error or the number of cleartext bytes sent.