libcoap  4.3.0rc3
DTLS Support (Internal)

CoAP DTLS Structures, Enums and Functions that are not exposed to applications. More...

Macros

#define COAP_DTLS_RETRANSMIT_MS   1000
 
#define COAP_DTLS_RETRANSMIT_TOTAL_MS   60000
 
#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...
 
int 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...
 
void 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...
 
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, int *connected)
 Create a new TLS client-side session. More...
 
void * coap_tls_new_server_session (coap_session_t *coap_session, int *connected)
 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_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_tcoap_session_new_dtls_session (coap_session_t *session, coap_tick_t now)
 Create a new DTLS session for the session. More...
 

Detailed Description

CoAP DTLS Structures, Enums and Functions that are not exposed to applications.

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

◆ COAP_DTLS_RETRANSMIT_MS

#define COAP_DTLS_RETRANSMIT_MS   1000

Definition at line 23 of file coap_dtls_internal.h.

◆ COAP_DTLS_RETRANSMIT_TOTAL_MS

#define COAP_DTLS_RETRANSMIT_TOTAL_MS   60000

Definition at line 26 of file coap_dtls_internal.h.

Function Documentation

◆ 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_contextThe 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_contextThe CoAP context.
setup_dataA 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_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 ( 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_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_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_contextThe CoAP context.
setup_dataA structure containing setup data originally passed into coap_context_set_psk2().
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.

Parameters
dtls_contextThe 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_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.

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

Get DTLS overhead over cleartext PDUs.

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

Get next timeout for this session.

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_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
sessionThe session.
tls_libUpdated with the library type.
Returns
The TLS information.

◆ coap_dtls_handle_timeout()

void coap_dtls_handle_timeout ( coap_session_t coap_session)

Handle a DTLS timeout expiration.

Parameters
coap_sessionThe CoAP session.

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

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

Definition at line 125 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_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 ( 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_contextThe 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_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 ( coap_session_t coap_session,
const uint8_t *  data,
size_t  data_len 
)

Handling incoming data from a DTLS peer.

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

Send data to a DTLS peer.

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

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

Parameters
coap_sessionThe CoAP session.

◆ coap_dtls_shutdown()

void coap_dtls_shutdown ( void  )

Close down the underlying (D)TLS Library layer.

Definition at line 81 of file coap_notls.c.

+ 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 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 689 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 ( 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_sessionThe CoAP session.

◆ coap_tls_new_client_session()

void* coap_tls_new_client_session ( coap_session_t coap_session,
int *  connected 
)

Create a new TLS client-side session.

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 ( coap_session_t coap_session,
int *  connected 
)

Create a TLS new server-side session.

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

Read some data from a TLS peer.

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

Send data to a TLS peer, with implicit flush.

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.