libcoap 4.3.3

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_tcoap_get_session_client_psk_key (const coap_session_t *coap_session)
 Get the current client's PSK key. More...
 
const coap_bin_const_tcoap_get_session_client_psk_identity (const coap_session_t *coap_session)
 Get the current client's PSK identity. More...
 
const coap_bin_const_tcoap_get_session_server_psk_key (const coap_session_t *coap_session)
 Get the current server's PSK key. More...
 
const coap_bin_const_tcoap_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_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 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
sessionSession 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_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_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
sessionSession 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_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()

int coap_dtls_handle_timeout ( coap_session_t coap_session)

Handle a DTLS timeout expiration.

Parameters
coap_sessionThe 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_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.
+ 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 182 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.
+ 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_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.
+ 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_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()

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_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 130 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 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_sessionThe 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_sessionThe 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_sessionThe 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_sessionThe 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
sessionSession to add DTLS session to
nowThe 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
sessionSession 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
sessionSession 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_sessionThe 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_sessionThe 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_sessionThe 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_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.