DTLS Support

API functions 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_asn1_t
| The structure that holds the PKI ASN.1 (DER) 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...

## Macros

#define | COAP_DTLS_PKI_SETUP_VERSION 1
| Latest PKI setup version. More...

## Typedefs

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, struct 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, struct coap_session_t *coap_session, unsigned depth, int validated, void *arg)
| CN Validation call-back 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_asn1_t | coap_pki_key_asn1_t
| The structure that holds the PKI ASN.1 (DER) 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_sni_callback_t) (const char *sni, void *arg)
| Server Name Indication (SNI) Validation call-back that can be set up by coap_context_set_pki(). More...
typedef struct coap_dtls_pki_t | coap_dtls_pki_t
| The structure used for defining the PKI setup data to be used. More...

## Enumerations

enum | coap_tls_library_t { COAP_TLS_LIBRARY_NOTLS = 0, COAP_TLS_LIBRARY_TINYDTLS, COAP_TLS_LIBRARY_OPENSSL, COAP_TLS_LIBRARY_GNUTLS }
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 }
| 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...
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 functions for interfacing with DTLS libraries.

## Macro Definition Documentation

## COAP_DTLS_PKI_SETUP_VERSION

#define COAP_DTLS_PKI_SETUP_VERSION 1

Latest PKI setup version.

Definition at line 188 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, struct coap_session_t *coap_session, unsigned depth, int validated, void *arg)

CN Validation call-back 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.

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 100 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_t

typedef struct coap_dtls_pki_t coap_dtls_pki_t

The structure used for defining the PKI setup data to be used.

## coap_dtls_security_setup_t

typedef int(* coap_dtls_security_setup_t) (void *tls_session, struct 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 call-back. 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 79 of file coap_dtls.h.

## coap_dtls_sni_callback_t

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

Server Name Indication (SNI) Validation call-back 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 184 of file coap_dtls.h.

## 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_t

typedef struct coap_pki_key_pem_t coap_pki_key_pem_t

The structure that holds the PKI PEM 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 112 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.
COAP_PKI_KEY_ASN1 | The PKI key type is ASN.1 (DER)

Definition at line 133 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.

Definition at line 40 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 enabled, or `0` otherwise.

Definition at line 21 of file coap_notls.c.

Here is the caller graph for this function:

## 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 31 of file coap_notls.c.

Here is the caller graph for this function:

## coap_tls_is_supported()

int coap_tls_is_supported | ( | void |  | ) |

Check whether TLS is available.

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

Definition at line 26 of file coap_notls.c.

Here is the caller graph for this function: