API for interfacing with DTLS libraries. More...

Collaboration diagram for DTLS Support:

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_pki_key_define_t
	The structure that holds the PKI Definable key type 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.

#define	COAP_DTLS_CPSK_SETUP_VERSION 1
	Latest CPSK setup version.

#define	COAP_DTLS_SPSK_SETUP_VERSION 1
	Latest SPSK setup version.

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.

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

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

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.

typedef enum coap_pki_key_t	coap_pki_key_t
	The enum used for determining the PKI key formats.

typedef struct coap_pki_key_pem_t	coap_pki_key_pem_t
	The structure that holds the PKI PEM definitions.

typedef struct coap_pki_key_pem_buf_t	coap_pki_key_pem_buf_t
	The structure that holds the PKI PEM buffer definitions.

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

typedef struct coap_pki_key_pkcs11_t	coap_pki_key_pkcs11_t
	The structure that holds the PKI PKCS11 definitions.

typedef struct coap_pki_key_define_t	coap_pki_key_define_t
	The structure that holds the PKI Definable key type definitions.

typedef struct coap_dtls_key_t	coap_dtls_key_t
	The structure that holds the PKI key information.

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

typedef struct coap_dtls_cpsk_info_t	coap_dtls_cpsk_info_t
	The structure that holds the Client PSK information.

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

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

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.

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

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

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

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 , COAP_TLS_LIBRARY_WOLFSSL }

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 , COAP_PKI_KEY_DEFINE }
	The enum used for determining the PKI key formats. More...

enum	coap_pki_define_t { COAP_PKI_KEY_DEF_PEM = 0 , COAP_PKI_KEY_DEF_PEM_BUF , COAP_PKI_KEY_DEF_RPK_BUF , COAP_PKI_KEY_DEF_DER , COAP_PKI_KEY_DEF_DER_BUF , COAP_PKI_KEY_DEF_PKCS11 , COAP_PKI_KEY_DEF_PKCS11_RPK , COAP_PKI_KEY_DEF_ENGINE }
	The enum to define the format of the key parameter definition. More...

Functions
int	coap_tls_engine_configure (coap_str_const_t *conf_mem)
	Configure an ENGINE for a TLS library.

int	coap_tls_engine_remove (void)
	Remove a previously configured ENGINE from a TLS library.

coap_tls_version_t *	coap_get_tls_library_version (void)
	Determine the type and version of the underlying (D)TLS library.

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

◆ COAP_DTLS_HINT_LENGTH

#define COAP_DTLS_HINT_LENGTH 128

Definition at line 35 of file coap_dtls.h.

◆ COAP_DTLS_MAX_PSK

#define COAP_DTLS_MAX_PSK 64

Definition at line 41 of file coap_dtls.h.

◆ COAP_DTLS_MAX_PSK_IDENTITY

#define COAP_DTLS_MAX_PSK_IDENTITY 64

Definition at line 38 of file coap_dtls.h.

◆ COAP_DTLS_PKI_SETUP_VERSION

#define COAP_DTLS_PKI_SETUP_VERSION 1

Latest PKI setup version.

Definition at line 307 of file coap_dtls.h.

◆ COAP_DTLS_RPK_CERT_CN

#define COAP_DTLS_RPK_CERT_CN "RPK"

Definition at line 49 of file coap_dtls.h.

◆ COAP_DTLS_SPSK_SETUP_VERSION

#define COAP_DTLS_SPSK_SETUP_VERSION 1

Latest SPSK setup version.

Definition at line 496 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 134 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 473 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 400 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 303 of file coap_dtls.h.

◆ coap_dtls_pki_t

typedef struct coap_dtls_pki_t coap_dtls_pki_t

Definition at line 32 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 491 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 111 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_define_t

typedef struct coap_pki_key_define_t coap_pki_key_define_t

The structure that holds the PKI Definable key type 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 146 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 44 of file coap_dtls.h.

◆ coap_pki_define_t

enum coap_pki_define_t

The enum to define the format of the key parameter definition.

Enumerator
COAP_PKI_KEY_DEF_PEM	The PKI key type is PEM file. Length ignored, NULL terminated.
COAP_PKI_KEY_DEF_PEM_BUF	The PKI key type is PEM buffer. Length required.
COAP_PKI_KEY_DEF_RPK_BUF	The PKI key type is RPK in buffer. Length required.
COAP_PKI_KEY_DEF_DER	The PKI key type is DER file. Length ignored, NULL terminated.
COAP_PKI_KEY_DEF_DER_BUF	The PKI key type is DER buffer (ASN.1). Length required. Private Key Type required.
COAP_PKI_KEY_DEF_PKCS11	The PKI key type is PKCS11 (pkcs11:...). Length ignored, NULL terminated. User Pin optional.
COAP_PKI_KEY_DEF_PKCS11_RPK	The PKI key type is PKCS11 w/ RPK (pkcs11:...). Length ignored, NULL terminated. User Pin optional.
COAP_PKI_KEY_DEF_ENGINE	The PKI key type is to be passed to ENGINE. Length ignored, NULL terminated. Supported by OpenSSL only

Definition at line 233 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)
COAP_PKI_KEY_DEFINE	The individual PKI key types are Definable.

Definition at line 167 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.
COAP_TLS_LIBRARY_WOLFSSL	Using wolfSSL library.

Definition at line 70 of file coap_dtls.h.

Function Documentation

◆ 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 100 of file coap_notls.c.

Here is the caller graph for this function:

◆ coap_tls_engine_configure()

int coap_tls_engine_configure ( coap_str_const_t * conf_mem )

Configure an ENGINE for a TLS library.

(Currently only OpenSSL is supported)

Parameters

conf_mem The configuration to use in memory.

Returns: 1 if successful, or 0 if failure.

Definition at line 22 of file coap_notls.c.

◆ coap_tls_engine_remove()

int coap_tls_engine_remove ( void )

Remove a previously configured ENGINE from a TLS library.

(Currently only OpenSSL is supported) (This is automatically done when coap_free_context() is called)

Returns: 1 if successful, or 0 if failure.

Definition at line 28 of file coap_notls.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ COAP_DTLS_CPSK_SETUP_VERSION

◆ COAP_DTLS_HINT_LENGTH

◆ COAP_DTLS_MAX_PSK

◆ COAP_DTLS_MAX_PSK_IDENTITY

◆ COAP_DTLS_PKI_SETUP_VERSION

◆ COAP_DTLS_RPK_CERT_CN

◆ COAP_DTLS_SPSK_SETUP_VERSION

Typedef Documentation

◆ coap_asn1_privatekey_type_t

◆ coap_dtls_cn_callback_t

◆ coap_dtls_cpsk_info_t

◆ coap_dtls_cpsk_t

◆ coap_dtls_id_callback_t

◆ coap_dtls_ih_callback_t

◆ coap_dtls_key_t

◆ coap_dtls_pki_sni_callback_t

◆ coap_dtls_pki_t

◆ coap_dtls_psk_sni_callback_t

◆ coap_dtls_role_t

◆ coap_dtls_security_setup_t

◆ coap_dtls_spsk_info_t

◆ coap_dtls_spsk_t

◆ coap_pki_key_asn1_t

◆ coap_pki_key_define_t

◆ coap_pki_key_pem_buf_t

◆ coap_pki_key_pem_t

◆ coap_pki_key_pkcs11_t

◆ coap_pki_key_t

◆ coap_tls_library_t

◆ coap_tls_version_t

Enumeration Type Documentation

◆ coap_asn1_privatekey_type_t

◆ coap_dtls_role_t

◆ coap_pki_define_t

◆ coap_pki_key_t

◆ coap_tls_library_t

Function Documentation

◆ coap_get_tls_library_version()

◆ coap_tls_engine_configure()

◆ coap_tls_engine_remove()