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.

Check whether DTLS is available.

Definition at line 122 of file coap_dtls_gnutls.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:

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ COAP_DTLS_PKI_SETUP_VERSION

Typedef Documentation

◆ coap_asn1_privatekey_type_t

◆ coap_dtls_cn_callback_t

◆ coap_dtls_key_t

◆ coap_dtls_pki_t

◆ coap_dtls_security_setup_t

◆ coap_dtls_sni_callback_t

◆ coap_pki_key_asn1_t

◆ coap_pki_key_pem_t

◆ coap_pki_key_t

◆ coap_tls_library_t

◆ coap_tls_version_t

Enumeration Type Documentation

◆ coap_asn1_privatekey_type_t

◆ coap_pki_key_t

◆ coap_tls_library_t

Function Documentation

◆ coap_dtls_is_supported()

◆ coap_get_tls_library_version()

◆ coap_tls_is_supported()