libcoap 4.3.2rc2

Data Structures | Macros | Typedefs | Enumerations | Functions
DTLS Support
Application API

API for interfacing with DTLS libraries. More...

## Data Structures
struct | coap_tls_version_t
| The structure used for returning the underlying (D)TLS library information. More...
struct | coap_pki_key_pem_t
| The structure that holds the PKI PEM definitions. More...
struct | coap_pki_key_pem_buf_t
| The structure that holds the PKI PEM buffer definitions. More...
struct | coap_pki_key_asn1_t
| The structure that holds the PKI ASN.1 (DER) definitions. More...
struct | coap_pki_key_pkcs11_t
| The structure that holds the PKI PKCS11 definitions. More...
struct | coap_dtls_key_t
| The structure that holds the PKI key information. More...
struct | coap_dtls_pki_t
| The structure used for defining the PKI setup data to be used. More...
struct | coap_dtls_cpsk_info_t
| The structure that holds the Client PSK information. More...
struct | coap_dtls_cpsk_t
| The structure used for defining the Client PSK setup data to be used. More...
struct | coap_dtls_spsk_info_t
| The structure that holds the Server Pre-Shared Key and Identity Hint information. More...
struct | coap_dtls_spsk_t
| The structure used for defining the Server PSK setup data to be used. More...

## Macros
#define | COAP_DTLS_HINT_LENGTH 128
#define | COAP_DTLS_MAX_PSK_IDENTITY 64
#define | COAP_DTLS_MAX_PSK 64
#define | COAP_DTLS_RPK_CERT_CN "RPK"
#define | COAP_DTLS_PKI_SETUP_VERSION 1
| Latest PKI setup version. More...
#define | COAP_DTLS_CPSK_SETUP_VERSION 1
| Latest CPSK setup version. More...
#define | COAP_DTLS_SPSK_SETUP_VERSION 1
| Latest SPSK setup version. More...

## Typedefs
typedef struct coap_dtls_pki_t | coap_dtls_pki_t
typedef enum coap_dtls_role_t | coap_dtls_role_t
typedef enum coap_tls_library_t | coap_tls_library_t
typedef struct coap_tls_version_t | coap_tls_version_t
| The structure used for returning the underlying (D)TLS library information. More...
typedef int(* | coap_dtls_security_setup_t) (void *tls_session, coap_dtls_pki_t *setup_data)
| Additional Security setup handler that can be set up by coap_context_set_pki(). More...
typedef int(* | coap_dtls_cn_callback_t) (const char *cn, const uint8_t *asn1_public_cert, size_t asn1_length, coap_session_t *coap_session, unsigned int depth, int validated, void *arg)
| CN Validation callback that can be set up by coap_context_set_pki(). More...
typedef enum coap_asn1_privatekey_type_t | coap_asn1_privatekey_type_t
| The enum used for determining the provided PKI ASN.1 (DER) Private Key formats. More...
typedef enum coap_pki_key_t | coap_pki_key_t
| The enum used for determining the PKI key formats. More...
typedef struct coap_pki_key_pem_t | coap_pki_key_pem_t
| The structure that holds the PKI PEM definitions. More...
typedef struct coap_pki_key_pem_buf_t | coap_pki_key_pem_buf_t
| The structure that holds the PKI PEM buffer definitions. More...
typedef struct coap_pki_key_asn1_t | coap_pki_key_asn1_t
| The structure that holds the PKI ASN.1 (DER) definitions. More...
typedef struct coap_pki_key_pkcs11_t | coap_pki_key_pkcs11_t
| The structure that holds the PKI PKCS11 definitions. More...
typedef struct coap_dtls_key_t | coap_dtls_key_t
| The structure that holds the PKI key information. More...
typedef coap_dtls_key_t *(* | coap_dtls_pki_sni_callback_t) (const char *sni, void *arg)
| Server Name Indication (SNI) Validation callback that can be set up by coap_context_set_pki(). More...
typedef struct coap_dtls_cpsk_info_t | coap_dtls_cpsk_info_t
| The structure that holds the Client PSK information. More...
typedef const coap_dtls_cpsk_info_t *(* | coap_dtls_ih_callback_t) (coap_str_const_t *hint, coap_session_t *coap_session, void *arg)
| Identity Hint Validation callback that can be set up by coap_new_client_session_psk2(). More...
typedef struct coap_dtls_cpsk_t | coap_dtls_cpsk_t
| The structure used for defining the Client PSK setup data to be used. More...
typedef struct coap_dtls_spsk_info_t | coap_dtls_spsk_info_t
| The structure that holds the Server Pre-Shared Key and Identity Hint information. More...
typedef const coap_bin_const_t *(* | coap_dtls_id_callback_t) (coap_bin_const_t *identity, coap_session_t *coap_session, void *arg)
| Identity Validation callback that can be set up by coap_context_set_psk2(). More...
typedef const coap_dtls_spsk_info_t *(* | coap_dtls_psk_sni_callback_t) (const char *sni, coap_session_t *coap_session, void *arg)
| PSK SNI callback that can be set up by coap_context_set_psk2(). More...
typedef struct coap_dtls_spsk_t | coap_dtls_spsk_t
| The structure used for defining the Server PSK setup data to be used. More...

## Enumerations
enum | coap_dtls_role_t { COAP_DTLS_ROLE_CLIENT , COAP_DTLS_ROLE_SERVER }
enum | coap_tls_library_t { COAP_TLS_LIBRARY_NOTLS = 0 , COAP_TLS_LIBRARY_TINYDTLS , COAP_TLS_LIBRARY_OPENSSL , COAP_TLS_LIBRARY_GNUTLS , COAP_TLS_LIBRARY_MBEDTLS }
enum | coap_asn1_privatekey_type_t { COAP_ASN1_PKEY_NONE , COAP_ASN1_PKEY_RSA , COAP_ASN1_PKEY_RSA2 , COAP_ASN1_PKEY_DSA , COAP_ASN1_PKEY_DSA1 , COAP_ASN1_PKEY_DSA2 , COAP_ASN1_PKEY_DSA3 , COAP_ASN1_PKEY_DSA4 , COAP_ASN1_PKEY_DH , COAP_ASN1_PKEY_DHX , COAP_ASN1_PKEY_EC , COAP_ASN1_PKEY_HMAC , COAP_ASN1_PKEY_CMAC , COAP_ASN1_PKEY_TLS1_PRF , COAP_ASN1_PKEY_HKDF }
| The enum used for determining the provided PKI ASN.1 (DER) Private Key formats. More...
enum | coap_pki_key_t { COAP_PKI_KEY_PEM = 0 , COAP_PKI_KEY_ASN1 , COAP_PKI_KEY_PEM_BUF , COAP_PKI_KEY_PKCS11 }
| The enum used for determining the PKI key formats. More...

## Functions
int | coap_dtls_is_supported (void)
| Check whether DTLS is available. More...
int | coap_tls_is_supported (void)
| Check whether TLS is available. More...
int | coap_dtls_psk_is_supported (void)
| Check whether (D)TLS PSK is available. More...
int | coap_dtls_pki_is_supported (void)
| Check whether (D)TLS PKI is available. More...
int | coap_dtls_pkcs11_is_supported (void)
| Check whether (D)TLS PKCS11 is available. More...
int | coap_dtls_rpk_is_supported (void)
| Check whether (D)TLS RPK is available. More...
coap_tls_version_t * | coap_get_tls_library_version (void)
| Determine the type and version of the underlying (D)TLS library. More...

## Detailed Description

API for interfacing with DTLS libraries.

## Macro Definition Documentation

## ◆ COAP_DTLS_CPSK_SETUP_VERSION

#define COAP_DTLS_CPSK_SETUP_VERSION 1

Latest CPSK setup version.

Definition at line 373 of file coap_dtls.h.

## ◆ COAP_DTLS_HINT_LENGTH

#define COAP_DTLS_HINT_LENGTH 128

Definition at line 34 of file coap_dtls.h.

## ◆ COAP_DTLS_MAX_PSK

#define COAP_DTLS_MAX_PSK 64

Definition at line 40 of file coap_dtls.h.

## ◆ COAP_DTLS_MAX_PSK_IDENTITY

#define COAP_DTLS_MAX_PSK_IDENTITY 64

Definition at line 37 of file coap_dtls.h.

## ◆ COAP_DTLS_PKI_SETUP_VERSION

#define COAP_DTLS_PKI_SETUP_VERSION 1

Latest PKI setup version.

Definition at line 279 of file coap_dtls.h.

## ◆ COAP_DTLS_RPK_CERT_CN

#define COAP_DTLS_RPK_CERT_CN "RPK"

Definition at line 48 of file coap_dtls.h.

## ◆ COAP_DTLS_SPSK_SETUP_VERSION

#define COAP_DTLS_SPSK_SETUP_VERSION 1

Latest SPSK setup version.

Definition at line 460 of file coap_dtls.h.

## Typedef Documentation

## ◆ coap_asn1_privatekey_type_t

typedef enum coap_asn1_privatekey_type_t coap_asn1_privatekey_type_t

The enum used for determining the provided PKI ASN.1 (DER) Private Key formats.

## ◆ coap_dtls_cn_callback_t

typedef int(* coap_dtls_cn_callback_t) (const char *cn, const uint8_t *asn1_public_cert, size_t asn1_length, coap_session_t *coap_session, unsigned int depth, int validated, void *arg)

CN Validation callback that can be set up by coap_context_set_pki().

Invoked when libcoap has done the validation checks at the TLS level, but the application needs to check that the CN is allowed. CN is the SubjectAltName in the cert, if not present, then the leftmost Common Name (CN) component of the subject name. NOTE: If using RPK, then the Public Key does not contain a CN, but the content of COAP_DTLS_RPK_CERT_CN is presented for the `cn` parameter.

Parameters

  cn | The determined CN from the certificate
  asn1_public_cert | The ASN.1 DER encoded X.509 certificate
  asn1_length | The ASN.1 length
  coap_session | The CoAP session associated with the certificate update
  depth | Depth in cert chain. If 0, then client cert, else a CA
  validated | TLS layer can find no issues if 1
  arg | The same as was passed into coap_context_set_pki() in setup_data->cn_call_back_arg

Returns
  `1` if accepted, else `0` if to be rejected.

Definition at line 155 of file coap_dtls.h.

## ◆ coap_dtls_cpsk_info_t

typedef struct coap_dtls_cpsk_info_t coap_dtls_cpsk_info_t

The structure that holds the Client PSK information.

## ◆ coap_dtls_cpsk_t

typedef struct coap_dtls_cpsk_t coap_dtls_cpsk_t

The structure used for defining the Client PSK setup data to be used.

## ◆ coap_dtls_id_callback_t

typedef const coap_bin_const_t *(* coap_dtls_id_callback_t) (coap_bin_const_t *identity, coap_session_t *coap_session, void *arg)

Identity Validation callback that can be set up by coap_context_set_psk2().

Invoked when libcoap has done the validation checks at the TLS level, but the application needs to check that the Identity is allowed, and needs to use the appropriate Pre-Shared Key for the (D)TLS session.

Parameters

  identity | The client provided Identity
  coap_session | The CoAP session associated with the Identity Hint
  arg | The value as passed into coap_context_set_psk2() in setup_data->id_call_back_arg

Returns
  New coap_bin_const_t object containing the Pre-Shared Key or `NULL` on error. Note: This information will be duplicated into an internal structure.

Definition at line 437 of file coap_dtls.h.

## ◆ coap_dtls_ih_callback_t

typedef const coap_dtls_cpsk_info_t *(* coap_dtls_ih_callback_t) (coap_str_const_t *hint, coap_session_t *coap_session, void *arg)

Identity Hint Validation callback that can be set up by coap_new_client_session_psk2().

Invoked when libcoap has done the validation checks at the TLS level, but the application needs to check that the Identity Hint is allowed, and thus needs to use the appropriate PSK information for the Identity Hint for the (D)TLS session. Note: Identity Hint is not supported in (D)TLS1.3.

Parameters

  hint | The server provided Identity Hint
  coap_session | The CoAP session associated with the Identity Hint
  arg | The same as was passed into coap_new_client_session_psk2() in setup_data->ih_call_back_arg

Returns
  New coap_dtls_cpsk_info_t object or `NULL` on error.

Definition at line 368 of file coap_dtls.h.

## ◆ coap_dtls_key_t

typedef struct coap_dtls_key_t coap_dtls_key_t

The structure that holds the PKI key information.

## ◆ coap_dtls_pki_sni_callback_t

typedef coap_dtls_key_t *(* coap_dtls_pki_sni_callback_t) (const char *sni, void *arg)

Server Name Indication (SNI) Validation callback that can be set up by coap_context_set_pki().

Invoked if the SNI is not previously seen and prior to sending a certificate set back to the client so that the appropriate certificate set can be used based on the requesting SNI.

Parameters

  sni | The requested SNI
  arg | The same as was passed into coap_context_set_pki() in setup_data->sni_call_back_arg

Returns
  New set of certificates to use, or `NULL` if SNI is to be rejected.

Definition at line 275 of file coap_dtls.h.

## ◆ coap_dtls_pki_t

typedef struct coap_dtls_pki_t coap_dtls_pki_t

Definition at line 31 of file coap_dtls.h.

## ◆ coap_dtls_psk_sni_callback_t

typedef const coap_dtls_spsk_info_t *(* coap_dtls_psk_sni_callback_t) (const char *sni, coap_session_t *coap_session, void *arg)

PSK SNI callback that can be set up by coap_context_set_psk2().

Invoked when libcoap has done the validation checks at the TLS level and the application needs to:- a) check that the SNI is allowed b) provide the appropriate PSK information for the (D)TLS session.

Parameters

  sni | The client provided SNI
  coap_session | The CoAP session associated with the SNI
  arg | The same as was passed into coap_context_set_psk2() in setup_data->sni_call_back_arg

Returns
  New coap_dtls_spsk_info_t object or `NULL` on error.

Definition at line 455 of file coap_dtls.h.

## ◆ coap_dtls_role_t

typedef enum coap_dtls_role_t coap_dtls_role_t

## ◆ coap_dtls_security_setup_t

typedef int(* coap_dtls_security_setup_t) (void *tls_session, coap_dtls_pki_t *setup_data)

Additional Security setup handler that can be set up by coap_context_set_pki().

Invoked when libcoap has done the validation checks at the TLS level, but the application needs to do some additional checks/changes/updates.

Parameters

  tls_session | The security session definition - e.g. SSL * for OpenSSL. NULL if server callback. This will be dependent on the underlying TLS library - see coap_get_tls_library_version()
  setup_data | A structure containing setup data originally passed into coap_context_set_pki() or coap_new_client_session_pki().

Returns
  `1` if successful, else `0`.

Definition at line 132 of file coap_dtls.h.

## ◆ coap_dtls_spsk_info_t

typedef struct coap_dtls_spsk_info_t coap_dtls_spsk_info_t

The structure that holds the Server Pre-Shared Key and Identity Hint information.

## ◆ coap_dtls_spsk_t

typedef struct coap_dtls_spsk_t coap_dtls_spsk_t

The structure used for defining the Server PSK setup data to be used.

## ◆ coap_pki_key_asn1_t

typedef struct coap_pki_key_asn1_t coap_pki_key_asn1_t

The structure that holds the PKI ASN.1 (DER) definitions.

## ◆ coap_pki_key_pem_buf_t

typedef struct coap_pki_key_pem_buf_t coap_pki_key_pem_buf_t

The structure that holds the PKI PEM buffer definitions.

The certificates and private key data must be in PEM format.

Note: The Certs and Key should be NULL terminated strings for performance reasons (to save a potential buffer copy) and the length include this NULL terminator. It is not a requirement to have the NULL terminator though and the length must then reflect the actual data size.

## ◆ coap_pki_key_pem_t

typedef struct coap_pki_key_pem_t coap_pki_key_pem_t

The structure that holds the PKI PEM definitions.

## ◆ coap_pki_key_pkcs11_t

typedef struct coap_pki_key_pkcs11_t coap_pki_key_pkcs11_t

The structure that holds the PKI PKCS11 definitions.

## ◆ coap_pki_key_t

typedef enum coap_pki_key_t coap_pki_key_t

The enum used for determining the PKI key formats.

## ◆ coap_tls_library_t

typedef enum coap_tls_library_t coap_tls_library_t

## ◆ coap_tls_version_t

typedef struct coap_tls_version_t coap_tls_version_t

The structure used for returning the underlying (D)TLS library information.

## Enumeration Type Documentation

## ◆ coap_asn1_privatekey_type_t

enum coap_asn1_privatekey_type_t

The enum used for determining the provided PKI ASN.1 (DER) Private Key formats.

Enumerator
COAP_ASN1_PKEY_NONE | NONE.
COAP_ASN1_PKEY_RSA | RSA type.
COAP_ASN1_PKEY_RSA2 | RSA2 type.
COAP_ASN1_PKEY_DSA | DSA type.
COAP_ASN1_PKEY_DSA1 | DSA1 type.
COAP_ASN1_PKEY_DSA2 | DSA2 type.
COAP_ASN1_PKEY_DSA3 | DSA3 type.
COAP_ASN1_PKEY_DSA4 | DSA4 type.
COAP_ASN1_PKEY_DH | DH type.
COAP_ASN1_PKEY_DHX | DHX type.
COAP_ASN1_PKEY_EC | EC type.
COAP_ASN1_PKEY_HMAC | HMAC type.
COAP_ASN1_PKEY_CMAC | CMAC type.
COAP_ASN1_PKEY_TLS1_PRF | TLS1_PRF type.
COAP_ASN1_PKEY_HKDF | HKDF type.

Definition at line 167 of file coap_dtls.h.

## ◆ coap_dtls_role_t

enum 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 43 of file coap_dtls.h.

## ◆ coap_pki_key_t

enum coap_pki_key_t

The enum used for determining the PKI key formats.

Enumerator
COAP_PKI_KEY_PEM | The PKI key type is PEM file.
COAP_PKI_KEY_ASN1 | The PKI key type is ASN.1 (DER) buffer.
COAP_PKI_KEY_PEM_BUF | The PKI key type is PEM buffer.
COAP_PKI_KEY_PKCS11 | The PKI key type is PKCS11 (DER)

Definition at line 188 of file coap_dtls.h.

## ◆ coap_tls_library_t

enum coap_tls_library_t

Enumerator
COAP_TLS_LIBRARY_NOTLS | No DTLS library.
COAP_TLS_LIBRARY_TINYDTLS | Using TinyDTLS library.
COAP_TLS_LIBRARY_OPENSSL | Using OpenSSL library.
COAP_TLS_LIBRARY_GNUTLS | Using GnuTLS library.
COAP_TLS_LIBRARY_MBEDTLS | Using Mbed TLS library.

Definition at line 92 of file coap_dtls.h.

## Function Documentation

## ◆ coap_dtls_is_supported()

int coap_dtls_is_supported | ( | void |  | ) |

Check whether DTLS is available.

Returns
  `1` if support for DTLS is available, or `0` otherwise.

Definition at line 23 of file coap_notls.c.

## ◆ coap_dtls_pkcs11_is_supported()

int coap_dtls_pkcs11_is_supported | ( | void |  | ) |

Check whether (D)TLS PKCS11 is available.

Returns
  `1` if support for (D)TLS PKCS11 is available, or `0` otherwise.

Definition at line 55 of file coap_notls.c.

## ◆ coap_dtls_pki_is_supported()

int coap_dtls_pki_is_supported | ( | void |  | ) |

Check whether (D)TLS PKI is available.

Returns
  `1` if support for (D)TLS PKI is available, or `0` otherwise.

Definition at line 46 of file coap_notls.c.

## ◆ coap_dtls_psk_is_supported()

int coap_dtls_psk_is_supported | ( | void |  | ) |

Check whether (D)TLS PSK is available.

Returns
  `1` if support for (D)TLS PSK is available, or `0` otherwise.

Definition at line 37 of file coap_notls.c.

## ◆ coap_dtls_rpk_is_supported()

int coap_dtls_rpk_is_supported | ( | void |  | ) |

Check whether (D)TLS RPK is available.

Returns
  `1` if support for (D)TLS RPK is available, or `0` otherwise.

Definition at line 64 of file coap_notls.c.

## ◆ coap_get_tls_library_version()

coap_tls_version_t * coap_get_tls_library_version | ( | void |  | ) |

Determine the type and version of the underlying (D)TLS library.

Returns
  The version and type of library libcoap was compiled against.

Definition at line 69 of file coap_notls.c.

## ◆ coap_tls_is_supported()

int coap_tls_is_supported | ( | void |  | ) |

Check whether TLS is available.

Returns
  `1` if support for TLS is available, or `0` otherwise.

Definition at line 28 of file coap_notls.c.