libcoap 4.3.3
DTLS Support

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_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_tcoap_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

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
cnThe determined CN from the certificate
asn1_public_certThe ASN.1 DER encoded X.509 certificate
asn1_lengthThe ASN.1 length
coap_sessionThe CoAP session associated with the certificate update
depthDepth in cert chain. If 0, then client cert, else a CA
validatedTLS layer can find no issues if 1
argThe 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

The structure that holds the Client PSK information.

◆ 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
identityThe client provided Identity
coap_sessionThe CoAP session associated with the Identity Hint
argThe 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
hintThe server provided Identity Hint
coap_sessionThe CoAP session associated with the Identity Hint
argThe 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

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
sniThe requested SNI
argThe 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

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
sniThe client provided SNI
coap_sessionThe CoAP session associated with the SNI
argThe 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

◆ 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_sessionThe 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_dataA 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

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

◆ coap_dtls_spsk_t

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

◆ coap_pki_key_asn1_t

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

◆ 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

The structure that holds the PKI PEM definitions.

◆ coap_pki_key_pkcs11_t

The structure that holds the PKI PKCS11 definitions.

◆ coap_pki_key_t

The enum used for determining the PKI key formats.

◆ coap_tls_library_t

◆ coap_tls_version_t

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

Enumeration Type Documentation

◆ 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

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

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

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.

+ Here is the caller graph for this function:

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

+ Here is the caller graph for this function:

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

+ Here is the caller graph for this function:

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

+ Here is the caller graph for this function:

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

+ 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 69 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 available, or 0 otherwise.

Definition at line 28 of file coap_notls.c.

+ Here is the caller graph for this function: