coap_dtls.h
Go to the documentation of this file.
/*
* coap_dtls.h -- (Datagram) Transport Layer Support for libcoap
*
* Copyright (C) 2016 Olaf Bergmann <bergmann@tzi.org>
* Copyright (C) 2017 Jean-Claude Michelou <jcm@spinetix.com>
*
* This file is part of the CoAP library libcoap. Please see README for terms
* of use.
*/
#ifndef COAP_DTLS_H_
#define COAP_DTLS_H_
#include "coap_time.h"
struct coap_context_t;
struct coap_session_t;
struct coap_dtls_pki_t;
int coap_dtls_is_supported(void);
int coap_tls_is_supported(void);
typedef 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_t;
typedef struct coap_tls_version_t {
uint64_t version;
coap_tls_library_t type;
uint64_t built_version;
} coap_tls_version_t;
coap_tls_version_t *coap_get_tls_library_version(void);
typedef int (*coap_dtls_security_setup_t)(void* tls_session,
struct coap_dtls_pki_t *setup_data);
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);
typedef 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
} coap_asn1_privatekey_type_t;
typedef enum coap_pki_key_t {
COAP_PKI_KEY_PEM = 0,
COAP_PKI_KEY_ASN1,
} coap_pki_key_t;
typedef struct coap_pki_key_pem_t {
const char *ca_file;
const char *public_cert;
const char *private_key;
} coap_pki_key_pem_t;
typedef struct coap_pki_key_asn1_t {
const uint8_t *ca_cert;
const uint8_t *public_cert;
const uint8_t *private_key;
size_t ca_cert_len;
size_t public_cert_len;
size_t private_key_len;
coap_asn1_privatekey_type_t private_key_type;
} coap_pki_key_asn1_t;
typedef struct coap_dtls_key_t {
coap_pki_key_t key_type;
union {
coap_pki_key_pem_t pem;
coap_pki_key_asn1_t asn1;
} key;
} coap_dtls_key_t;
typedef coap_dtls_key_t *(*coap_dtls_sni_callback_t)(const char *sni,
void* arg);
#define COAP_DTLS_PKI_SETUP_VERSION 1
typedef struct coap_dtls_pki_t {
uint8_t version;
/* Options to enable different TLS functionality in libcoap */
uint8_t verify_peer_cert;
uint8_t require_peer_cert;
uint8_t allow_self_signed;
uint8_t allow_expired_certs;
uint8_t cert_chain_validation;
uint8_t cert_chain_verify_depth;
uint8_t check_cert_revocation;
uint8_t allow_no_crl;
uint8_t allow_expired_crl;
uint8_t reserved[6];
/* 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.
*/
coap_dtls_cn_callback_t validate_cn_call_back;
void *cn_call_back_arg;
coap_dtls_sni_callback_t validate_sni_call_back;
void *sni_call_back_arg;
coap_dtls_security_setup_t additional_tls_setup_call_back;
char* client_sni;
coap_dtls_key_t pki_key;
} coap_dtls_pki_t;
void *
coap_dtls_new_context(struct coap_context_t *coap_context);
typedef enum coap_dtls_role_t {
COAP_DTLS_ROLE_CLIENT,
COAP_DTLS_ROLE_SERVER
} coap_dtls_role_t;
int
coap_dtls_context_set_psk(struct coap_context_t *coap_context,
const char *identity_hint,
coap_dtls_role_t role);
int
coap_dtls_context_set_pki(struct coap_context_t *coap_context,
coap_dtls_pki_t *setup_data,
coap_dtls_role_t role);
int
coap_dtls_context_set_pki_root_cas(struct coap_context_t *coap_context,
const char *ca_file,
const char *ca_dir);
int coap_dtls_context_check_keys_enabled(struct coap_context_t *coap_context);
void coap_dtls_free_context(void *dtls_context);
void *coap_dtls_new_client_session(struct coap_session_t *coap_session);
void *coap_dtls_new_server_session(struct coap_session_t *coap_session);
void coap_dtls_free_session(struct coap_session_t *coap_session);
void coap_dtls_session_update_mtu(struct coap_session_t *coap_session);
int coap_dtls_send(struct coap_session_t *coap_session,
const uint8_t *data,
size_t data_len);
int coap_dtls_is_context_timeout(void);
coap_tick_t coap_dtls_get_context_timeout(void *dtls_context);
coap_tick_t coap_dtls_get_timeout(struct coap_session_t *coap_session,
coap_tick_t now);
void coap_dtls_handle_timeout(struct coap_session_t *coap_session);
int coap_dtls_receive(struct coap_session_t *coap_session,
const uint8_t *data,
size_t data_len);
int coap_dtls_hello(struct coap_session_t *coap_session,
const uint8_t *data,
size_t data_len);
unsigned int coap_dtls_get_overhead(struct coap_session_t *coap_session);
void *coap_tls_new_client_session(struct coap_session_t *coap_session, int *connected);
void *coap_tls_new_server_session(struct coap_session_t *coap_session, int *connected);
void coap_tls_free_session( struct coap_session_t *coap_session );
ssize_t coap_tls_write(struct coap_session_t *coap_session,
const uint8_t *data,
size_t data_len
);
ssize_t coap_tls_read(struct coap_session_t *coap_session,
uint8_t *data,
size_t data_len
);
void coap_dtls_startup(void);
void coap_dtls_set_log_level(int level);
int coap_dtls_get_log_level(void);
#endif /* COAP_DTLS_H */
coap_dtls_set_log_level
void coap_dtls_set_log_level(int level)
Sets the (D)TLS logging level to the specified level.
Definition: coap_notls.c:74
coap_session_t
Definition: coap_session.h:59
coap_dtls_free_context
void coap_dtls_free_context(void *dtls_context)
Releases the storage allocated for dtls_context.
COAP_ASN1_PKEY_NONE
NONE.
Definition: coap_dtls.h:113
COAP_TLS_LIBRARY_TINYDTLS
Using TinyDTLS library.
Definition: coap_dtls.h:42
coap_pki_key_pem_t
struct coap_pki_key_pem_t coap_pki_key_pem_t
The structure that holds the PKI PEM definitions.
coap_dtls_pki_t::allow_self_signed
uint8_t allow_self_signed
1 if self signed certs are allowed
Definition: coap_dtls.h:199
COAP_PKI_KEY_ASN1
The PKI key type is ASN.1 (DER)
Definition: coap_dtls.h:135
COAP_ASN1_PKEY_EC
EC type.
Definition: coap_dtls.h:123
coap_dtls_new_context
void * coap_dtls_new_context(struct coap_context_t *coap_context)
Creates a new DTLS context for the given coap_context.
coap_dtls_key_t::key_type
coap_pki_key_t key_type
key format type
Definition: coap_dtls.h:164
coap_dtls_pki_t
struct coap_dtls_pki_t coap_dtls_pki_t
The structure used for defining the PKI setup data to be used.
coap_dtls_pki_t::version
uint8_t version
Definition: coap_dtls.h:194
coap_dtls_get_log_level
int coap_dtls_get_log_level(void)
Get the current (D)TLS logging.
Definition: coap_notls.c:79
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)
Set the DTLS context&#39;s default PSK information.
coap_time.h
Clock Handling.
COAP_DTLS_ROLE_SERVER
Internal function invoked for server.
Definition: coap_dtls.h:268
COAP_ASN1_PKEY_HKDF
HKDF type.
Definition: coap_dtls.h:127
coap_dtls_is_supported
int coap_dtls_is_supported(void)
Check whether DTLS is available.
Definition: coap_notls.c:21
coap_dtls_pki_t::sni_call_back_arg
void * sni_call_back_arg
Passed in to the sni call-back function.
Definition: coap_dtls.h:229
coap_tls_version_t
struct coap_tls_version_t coap_tls_version_t
The structure used for returning the underlying (D)TLS library information.
coap_dtls_pki_t::verify_peer_cert
uint8_t verify_peer_cert
Set to 1 to support this version of the struct.
Definition: coap_dtls.h:197
coap_dtls_pki_t::allow_no_crl
uint8_t allow_no_crl
1 ignore if CRL not there
Definition: coap_dtls.h:204
coap_tls_version_t::version
uint64_t version
(D)TLS runtime Library Version
Definition: coap_dtls.h:52
coap_tls_new_server_session
void * coap_tls_new_server_session(struct coap_session_t *coap_session, int *connected)
Create a TLS new server-side session.
coap_dtls_new_client_session
void * coap_dtls_new_client_session(struct coap_session_t *coap_session)
Create a new client-side session.
coap_tls_new_client_session
void * coap_tls_new_client_session(struct coap_session_t *coap_session, int *connected)
Create a new TLS client-side session.
COAP_ASN1_PKEY_RSA2
RSA2 type.
Definition: coap_dtls.h:115
coap_dtls_pki_t::validate_sni_call_back
coap_dtls_sni_callback_t validate_sni_call_back
SNI check call-back function.
Definition: coap_dtls.h:228
COAP_ASN1_PKEY_HMAC
HMAC type.
Definition: coap_dtls.h:124
COAP_ASN1_PKEY_DSA1
DSA1 type.
Definition: coap_dtls.h:117
COAP_ASN1_PKEY_DSA
DSA type.
Definition: coap_dtls.h:116
coap_dtls_pki_t::additional_tls_setup_call_back
coap_dtls_security_setup_t additional_tls_setup_call_back
Additional Security call-back handler that is invoked when libcoap has done the standerd, defined validation checks at the TLS level, If not NULL, called from within the TLS Client Hello connection setup.
Definition: coap_dtls.h:236
COAP_TLS_LIBRARY_NOTLS
No DTLS library.
Definition: coap_dtls.h:41
coap_tls_is_supported
int coap_tls_is_supported(void)
Check whether TLS is available.
Definition: coap_notls.c:26
coap_tls_library_t
coap_tls_library_t
Definition: coap_dtls.h:40
coap_dtls_new_server_session
void * coap_dtls_new_server_session(struct coap_session_t *coap_session)
Create a new DTLS server-side session.
coap_tls_version_t::type
coap_tls_library_t type
Library type.
Definition: coap_dtls.h:53
coap_dtls_get_timeout
coap_tick_t coap_dtls_get_timeout(struct coap_session_t *coap_session, coap_tick_t now)
Get next timeout for this session.
coap_dtls_key_t
struct coap_dtls_key_t coap_dtls_key_t
The structure that holds the PKI key information.
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.
Definition: coap_notls.c:31
coap_tls_write
ssize_t coap_tls_write(struct coap_session_t *coap_session, const uint8_t *data, size_t data_len)
Send data to a TLS peer, with implicit flush.
coap_pki_key_pem_t::private_key
const char * private_key
File location of Private Key in PEM format.
Definition: coap_dtls.h:144
coap_dtls_pki_t::require_peer_cert
uint8_t require_peer_cert
1 if peer cert is required
Definition: coap_dtls.h:198
coap_dtls_pki_t::pki_key
coap_dtls_key_t pki_key
PKI key definition.
Definition: coap_dtls.h:242
coap_dtls_key_t::pem
coap_pki_key_pem_t pem
for PEM keys
Definition: coap_dtls.h:166
coap_dtls_pki_t::client_sni
char * client_sni
If not NULL, SNI to use in client TLS setup.
Definition: coap_dtls.h:238
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)
Set the dtls context&#39;s default Root CA information for a client or server.
coap_tick_t
uint64_t coap_tick_t
This data type represents internal timer ticks with COAP_TICKS_PER_SECOND resolution.
Definition: coap_time.h:93
coap_dtls_key_t
The structure that holds the PKI key information.
Definition: coap_dtls.h:163
coap_pki_key_asn1_t::public_cert
const uint8_t * public_cert
ASN1 (DER) Public Cert.
Definition: coap_dtls.h:152
coap_pki_key_pem_t::ca_file
const char * ca_file
File location of Common CA in PEM format.
Definition: coap_dtls.h:142
coap_pki_key_asn1_t::ca_cert_len
size_t ca_cert_len
ASN1 CA Cert length.
Definition: coap_dtls.h:154
COAP_PKI_KEY_PEM
The PKI key type is PEM.
Definition: coap_dtls.h:134
COAP_ASN1_PKEY_RSA
RSA type.
Definition: coap_dtls.h:114
coap_tls_version_t
The structure used for returning the underlying (D)TLS library information.
Definition: coap_dtls.h:51
COAP_ASN1_PKEY_DSA4
DSA4 type.
Definition: coap_dtls.h:120
coap_dtls_pki_t::cert_chain_validation
uint8_t cert_chain_validation
1 if to check cert_chain_verify_depth
Definition: coap_dtls.h:201
coap_pki_key_asn1_t
struct coap_pki_key_asn1_t coap_pki_key_asn1_t
The structure that holds the PKI ASN.1 (DER) definitions.
COAP_TLS_LIBRARY_OPENSSL
Using OpenSSL library.
Definition: coap_dtls.h:43
coap_pki_key_pem_t
The structure that holds the PKI PEM definitions.
Definition: coap_dtls.h:141
COAP_DTLS_ROLE_CLIENT
Internal function invoked for client.
Definition: coap_dtls.h:267
coap_pki_key_asn1_t::private_key
const uint8_t * private_key
ASN1 (DER) Private Key.
Definition: coap_dtls.h:153
COAP_ASN1_PKEY_DSA3
DSA3 type.
Definition: coap_dtls.h:119
coap_dtls_security_setup_t
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().
Definition: coap_dtls.h:79
coap_dtls_pki_t::validate_cn_call_back
coap_dtls_cn_callback_t validate_cn_call_back
CN check call-back function.
Definition: coap_dtls.h:220
COAP_TLS_LIBRARY_GNUTLS
Using GnuTLS library.
Definition: coap_dtls.h:44
coap_dtls_get_overhead
unsigned int coap_dtls_get_overhead(struct coap_session_t *coap_session)
Get DTLS overhead over cleartext PDUs.
coap_dtls_pki_t::allow_expired_certs
uint8_t allow_expired_certs
1 if expired certs are allowed
Definition: coap_dtls.h:200
coap_dtls_pki_t::check_cert_revocation
uint8_t check_cert_revocation
1 if revocation checks wanted
Definition: coap_dtls.h:203
coap_dtls_role_t
coap_dtls_role_t
Definition: coap_dtls.h:266
coap_dtls_session_update_mtu
void coap_dtls_session_update_mtu(struct coap_session_t *coap_session)
Notify of a change in the CoAP session&#39;s MTU, for example after a PMTU update.
coap_tls_free_session
void coap_tls_free_session(struct coap_session_t *coap_session)
Terminates the TLS session (may send an ALERT if necessary) then frees the underlying TLS library obj...
coap_dtls_get_context_timeout
coap_tick_t coap_dtls_get_context_timeout(void *dtls_context)
Do all pending retransmits and get next timeout.
coap_dtls_context_check_keys_enabled
int coap_dtls_context_check_keys_enabled(struct coap_context_t *coap_context)
Check whether one of the coap_dtls_context_set_{psk|pki}() functions have been called.
coap_dtls_pki_t::cn_call_back_arg
void * cn_call_back_arg
Passed in to the CN call-back function.
Definition: coap_dtls.h:221
coap_asn1_privatekey_type_t
coap_asn1_privatekey_type_t
The enum used for determining the provided PKI ASN.1 (DER) Private Key formats.
Definition: coap_dtls.h:112
coap_dtls_pki_t::allow_expired_crl
uint8_t allow_expired_crl
1 if expired crl is allowed
Definition: coap_dtls.h:205
coap_dtls_handle_timeout
void coap_dtls_handle_timeout(struct coap_session_t *coap_session)
Handle a DTLS timeout expiration.
coap_dtls_pki_t
The structure used for defining the PKI setup data to be used.
Definition: coap_dtls.h:193
coap_pki_key_asn1_t::private_key_type
coap_asn1_privatekey_type_t private_key_type
Private Key Type.
Definition: coap_dtls.h:157
coap_dtls_pki_t::cert_chain_verify_depth
uint8_t cert_chain_verify_depth
recommended depth is 3
Definition: coap_dtls.h:202
coap_dtls_free_session
void coap_dtls_free_session(struct coap_session_t *coap_session)
Terminates the DTLS session (may send an ALERT if necessary) then frees the underlying TLS library ob...
coap_dtls_receive
int coap_dtls_receive(struct coap_session_t *coap_session, const uint8_t *data, size_t data_len)
Handling incoming data from a DTLS peer.
coap_pki_key_pem_t::public_cert
const char * public_cert
File location of Public Cert in PEM format.
Definition: coap_dtls.h:143
coap_dtls_hello
int coap_dtls_hello(struct coap_session_t *coap_session, const uint8_t *data, size_t data_len)
Handling client HELLO messages from a new candiate peer.
coap_dtls_startup
void coap_dtls_startup(void)
Initialize the underlying (D)TLS Library layer.
Definition: coap_notls.c:70
COAP_ASN1_PKEY_DH
DH type.
Definition: coap_dtls.h:121
COAP_ASN1_PKEY_DSA2
DSA2 type.
Definition: coap_dtls.h:118
coap_pki_key_asn1_t::ca_cert
const uint8_t * ca_cert
ASN1 (DER) Common CA Cert.
Definition: coap_dtls.h:151
uint8_t
unsigned char uint8_t
Definition: uthash.h:79
COAP_ASN1_PKEY_TLS1_PRF
TLS1_PRF type.
Definition: coap_dtls.h:126
coap_dtls_send
int coap_dtls_send(struct coap_session_t *coap_session, const uint8_t *data, size_t data_len)
Send data to a DTLS peer.
coap_pki_key_asn1_t::public_cert_len
size_t public_cert_len
ASN1 Public Cert length.
Definition: coap_dtls.h:155
coap_pki_key_asn1_t
The structure that holds the PKI ASN.1 (DER) definitions.
Definition: coap_dtls.h:150
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)
Set the DTLS context&#39;s default server PKI information.
COAP_ASN1_PKEY_DHX
DHX type.
Definition: coap_dtls.h:122
coap_tls_version_t::built_version
uint64_t built_version
(D)TLS Built against Library Version
Definition: coap_dtls.h:54
COAP_ASN1_PKEY_CMAC
CMAC type.
Definition: coap_dtls.h:125
coap_tls_read
ssize_t coap_tls_read(struct coap_session_t *coap_session, uint8_t *data, size_t data_len)
Read some data from a TLS peer.
coap_dtls_sni_callback_t
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().
Definition: coap_dtls.h:184
coap_context_t
The CoAP stack&#39;s global state is stored in a coap_context_t object.
Definition: net.h:147
coap_dtls_is_context_timeout
int coap_dtls_is_context_timeout(void)
Check if timeout is handled per CoAP session or per CoAP context.
Definition: coap_notls.c:114
coap_pki_key_asn1_t::private_key_len
size_t private_key_len
ASN1 Private Key length.
Definition: coap_dtls.h:156
coap_dtls_cn_callback_t
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().
Definition: coap_dtls.h:100
coap_pki_key_t
coap_pki_key_t
The enum used for determining the PKI key formats.
Definition: coap_dtls.h:133
coap_dtls_key_t::asn1
coap_pki_key_asn1_t asn1
for ASN.1 (DER) keys
Definition: coap_dtls.h:167