Loading...
Searching...
No Matches
DTLS Support
Libcoap Internal API

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_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 39 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 53 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 46 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_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 214 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 161 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 149 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.