libcoap 4.3.2rc2

Macros | Functions
DTLS Support
Libcoap Internal API

Internal API for DTLS Support. More...

## 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_t * | coap_get_session_client_psk_key (const coap_session_t *coap_session)
| Get the current client's PSK key. More...
const coap_bin_const_t * | coap_get_session_client_psk_identity (const coap_session_t *coap_session)
| Get the current client's PSK identity. More...
const coap_bin_const_t * | coap_get_session_server_psk_key (const coap_session_t *coap_session)
| Get the current server's PSK key. More...
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. 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_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 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

  session | Session to do the DTLS close on.

Definition at line 40 of file coap_dtls.c.

## ◆ 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().

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_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 21 of file coap_dtls.c.

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

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

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

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

## ◆ 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_shutdown()

void coap_dtls_shutdown | ( | void |  | ) |

Close down the underlying (D)TLS Library layer.

Definition at line 130 of file coap_notls.c.

## ◆ coap_dtls_startup()

void coap_dtls_startup | ( | void |  | ) |

Initialize the underlying (D)TLS Library layer.

Definition at line 118 of file coap_notls.c.

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

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_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 69 of file coap_dtls.c.

## ◆ 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 50 of file coap_dtls.c.

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

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

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