libcoap  4.2.0
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_TLS_LIBRARY_NOTLS   0
 No DTLS library. More...
 
#define COAP_TLS_LIBRARY_TINYDTLS   1
 Using TinyDTLS library. More...
 
#define COAP_TLS_LIBRARY_OPENSSL   2
 Using OpenSSL library. More...
 
#define COAP_TLS_LIBRARY_GNUTLS   3
 Using GnuTLS library. More...
 
#define COAP_DTLS_PKI_SETUP_VERSION   1
 Latest PKI setup version. More...
 

Typedefs

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, 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_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_tcoap_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 186 of file coap_dtls.h.

◆ COAP_TLS_LIBRARY_GNUTLS

#define COAP_TLS_LIBRARY_GNUTLS   3

Using GnuTLS library.

Definition at line 41 of file coap_dtls.h.

◆ COAP_TLS_LIBRARY_NOTLS

#define COAP_TLS_LIBRARY_NOTLS   0

No DTLS library.

Definition at line 38 of file coap_dtls.h.

◆ COAP_TLS_LIBRARY_OPENSSL

#define COAP_TLS_LIBRARY_OPENSSL   2

Using OpenSSL library.

Definition at line 40 of file coap_dtls.h.

◆ COAP_TLS_LIBRARY_TINYDTLS

#define COAP_TLS_LIBRARY_TINYDTLS   1

Using TinyDTLS library.

Definition at line 39 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 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
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 98 of file coap_dtls.h.

◆ coap_dtls_key_t

The structure that holds the PKI key information.

◆ 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_sessionThe 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_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 77 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
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 182 of file coap_dtls.h.

◆ coap_pki_key_asn1_t

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

◆ coap_pki_key_pem_t

The structure that holds the PKI PEM definitions.

◆ coap_pki_key_t

The enum used for determining the PKI key formats.

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

COAP_PKI_KEY_ASN1 

The PKI key type is ASN.1 (DER)

Definition at line 131 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 891 of file coap_dtls.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 33 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 28 of file coap_notls.c.

+ Here is the caller graph for this function: