Documentation
Includes
coap_session.h
#include "coap_session.h"
pdu.h
#include "pdu.h"
Macros
Marco COAP_DTLS_H_
#define COAP_DTLS_H_
Marco COAP_TLS_LIBRARY_NOTLS
#define COAP_TLS_LIBRARY_NOTLS 0 /**< No DTLS library */
Marco COAP_TLS_LIBRARY_TINYDTLS
#define COAP_TLS_LIBRARY_TINYDTLS 1 /**< Using TinyDTLS library */
Marco COAP_TLS_LIBRARY_OPENSSL
#define COAP_TLS_LIBRARY_OPENSSL 2 /**< Using OpenSSL library */
Marco COAP_TLS_LIBRARY_GNUTLS
#define COAP_TLS_LIBRARY_GNUTLS 3 /**< Using GnuTLS library */
Marco COAP_DTLS_PKI_SETUP_VERSION
#define COAP_DTLS_PKI_SETUP_VERSION 1 /**< Latest PKI setup version */
Functions
Func coap_dtls_is_supported
int coap_dtls_is_supported(void);
Func coap_tls_is_supported
int coap_tls_is_supported(void);
Func coap_dtls_new_context
void *
coap_dtls_new_context(struct coap_context_t *coap_context);
Func coap_dtls_context_set_psk
int
coap_dtls_context_set_psk(struct coap_context_t *coap_context,
const char *identity_hint,
coap_dtls_role_t role);
Func coap_dtls_context_set_pki
int
coap_dtls_context_set_pki(struct coap_context_t *coap_context,
coap_dtls_pki_t *setup_data,
coap_dtls_role_t role);
Func coap_dtls_context_set_pki_root_cas
int
coap_dtls_context_set_pki_root_cas(struct coap_context_t *coap_context,
const char *ca_file,
const char *ca_dir);
Func coap_dtls_context_check_keys_enabled
int coap_dtls_context_check_keys_enabled(struct coap_context_t *coap_context);
Func coap_dtls_free_context
void coap_dtls_free_context(void *dtls_context);
Func coap_dtls_new_client_session
void *coap_dtls_new_client_session(coap_session_t *coap_session);
Func coap_dtls_new_server_session
void *coap_dtls_new_server_session(coap_session_t *coap_session);
Func coap_dtls_free_session
void coap_dtls_free_session(coap_session_t *coap_session);
Func coap_dtls_session_update_mtu
void coap_dtls_session_update_mtu(coap_session_t *coap_session);
Func coap_dtls_send
int coap_dtls_send(coap_session_t *coap_session,
const uint8_t *data,
size_t data_len);
Func coap_dtls_is_context_timeout
int coap_dtls_is_context_timeout(void);
Func coap_dtls_get_context_timeout
coap_tick_t coap_dtls_get_context_timeout(void *dtls_context);
Func coap_dtls_get_timeout
coap_tick_t coap_dtls_get_timeout(coap_session_t *coap_session);
Func coap_dtls_handle_timeout
void coap_dtls_handle_timeout(coap_session_t *coap_session);
Func coap_dtls_receive
int coap_dtls_receive(coap_session_t *coap_session,
const uint8_t *data,
size_t data_len);
Func coap_dtls_hello
int coap_dtls_hello(coap_session_t *coap_session,
const uint8_t *data,
size_t data_len);
Func coap_dtls_get_overhead
unsigned int coap_dtls_get_overhead(coap_session_t *coap_session);
Func coap_tls_new_client_session
void *coap_tls_new_client_session(coap_session_t *coap_session, int *connected);
Func coap_tls_new_server_session
void *coap_tls_new_server_session(coap_session_t *coap_session, int *connected);
Func coap_tls_free_session
void coap_tls_free_session( coap_session_t *coap_session );
Func coap_tls_write
ssize_t coap_tls_write(coap_session_t *coap_session,
const uint8_t *data,
size_t data_len
);
Func coap_tls_read
ssize_t coap_tls_read(coap_session_t *coap_session,
uint8_t *data,
size_t data_len
);
Func coap_dtls_startup
void coap_dtls_startup(void);
Func coap_dtls_set_log_level
void coap_dtls_set_log_level(int level);
Func coap_dtls_get_log_level
int coap_dtls_get_log_level(void);
Vars
Variable coap_tls_version_t
coap_tls_version_t *coap_get_tls_library_version(void);
Variable coap_dtls_pki_t
struct coap_dtls_pki_t;
Consts
Types
Typedefs
Typedef coap_tls_version_t;
typedef struct coap_tls_version_t {
uint64_t version; /**< (D)TLS runtime Library Version */
int type; /**< Library type. One of COAP_TLS_LIBRARY_* */
uint64_t built_version; /**< (D)TLS Built against Library Version */
} coap_tls_version_t;
Typedef coap_dtls_security_setup_t
typedef int (*coap_dtls_security_setup_t)(void* tls_session,
struct coap_dtls_pki_t *setup_data);
Typedef 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);
Typedef coap_asn1_privatekey_type_t;
typedef enum coap_asn1_privatekey_type_t {
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 */
} coap_asn1_privatekey_type_t;
Typedef coap_pki_key_t;
typedef enum coap_pki_key_t {
COAP_PKI_KEY_PEM = 0, /**< The PKI key type is PEM */
COAP_PKI_KEY_ASN1, /**< The PKI key type is ASN.1 (DER) */
} coap_pki_key_t;
Typedef coap_pki_key_pem_t;
typedef struct coap_pki_key_pem_t {
const char *ca_file; /**< File location of Common CA in PEM format */
const char *public_cert; /**< File location of Public Cert in PEM format */
const char *private_key; /**< File location of Private Key in PEM format */
} coap_pki_key_pem_t;
Typedef coap_pki_key_asn1_t;
typedef struct coap_pki_key_asn1_t {
const uint8_t *ca_cert; /**< ASN1 (DER) Common CA Cert */
const uint8_t *public_cert; /**< ASN1 (DER) Public Cert */
const uint8_t *private_key; /**< ASN1 (DER) Private Key */
size_t ca_cert_len; /**< ASN1 CA Cert length */
size_t public_cert_len; /**< ASN1 Public Cert length */
size_t private_key_len; /**< ASN1 Private Key length */
coap_asn1_privatekey_type_t private_key_type; /**< Private Key Type */
} coap_pki_key_asn1_t;
Typedef key;
typedef struct coap_dtls_key_t {
coap_pki_key_t key_type; /**< key format type */
union {
coap_pki_key_pem_t pem; /**< for PEM keys */
coap_pki_key_asn1_t asn1; /**< for ASN.1 (DER) keys */
} key;
Typedef coap_dtls_key_t
typedef coap_dtls_key_t *(*coap_dtls_sni_callback_t)(const char *sni,
void* arg);
Typedef coap_dtls_pki_t;
typedef struct coap_dtls_pki_t {
uint8_t version; /** Set to 1 to support this version of the struct */
/* Options to enable different TLS functionality in libcoap */
uint8_t verify_peer_cert; /**< 1 if peer cert is to be verified */
uint8_t require_peer_cert; /**< 1 if peer cert is required */
uint8_t allow_self_signed; /**< 1 if self signed certs are allowed */
uint8_t allow_expired_certs; /**< 1 if expired certs are allowed */
uint8_t cert_chain_validation; /**< 1 if to check cert_chain_verify_depth */
uint8_t cert_chain_verify_depth; /**< recommended depth is 3 */
uint8_t check_cert_revocation; /**< 1 if revocation checks wanted */
uint8_t allow_no_crl; /**< 1 ignore if CRL not there */
uint8_t allow_expired_crl; /**< 1 if expired crl is allowed */
uint8_t reserved[6]; /**< Reserved - must be set to 0 for
future compatibility */
/* Size of 6 chosen to align to next
* parameter, so if newly defined option
* it can use one of the reserverd slot so
* no need to change
* COAP_DTLS_PKI_SETUP_VERSION and just
* decrement the reserved[] count.
*/
/** CN check call-back function.
* If not NULL, is called when the TLS connection has passed the configured
* TLS options above for the application to verify if the CN is valid.
*/
coap_dtls_cn_callback_t validate_cn_call_back;
void *cn_call_back_arg; /**< Passed in to the CN call-back function */
/** SNI check call-back function.
* If not @p NULL, called 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.
*/
coap_dtls_sni_callback_t validate_sni_call_back;
void *sni_call_back_arg; /**< Passed in to the sni call-back function */
/** Additional Security call-back handler that is invoked when libcoap has
* done the standerd, defined validation checks at the TLS level,
* If not @p NULL, called from within the TLS Client Hello connection
* setup.
*/
coap_dtls_security_setup_t additional_tls_setup_call_back;
char* client_sni; /**< If not NULL, SNI to use in client TLS setup.
Owned by the client app and must remain valid
during the call to coap_new_client_session_pki() */
coap_dtls_key_t pki_key; /**< PKI key definition */
} coap_dtls_pki_t;
Typedef coap_dtls_role_t;
typedef enum coap_dtls_role_t {
COAP_DTLS_ROLE_CLIENT, /**< Internal function invoked for client */
COAP_DTLS_ROLE_SERVER /**< Internal function invoked for server */
} coap_dtls_role_t;