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_time.h
Clock Handling.
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_get_overhead
unsigned int coap_dtls_get_overhead(struct coap_session_t *coap_session)
Get DTLS overhead over cleartext PDUs.
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_startup
void coap_dtls_startup(void)
Initialize the underlying (D)TLS Library layer.
Definition: coap_notls.c:70
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_dtls_new_client_session
void * coap_dtls_new_client_session(struct coap_session_t *coap_session)
Create a new client-side session.
coap_dtls_role_t
coap_dtls_role_t
Definition: coap_dtls.h:266
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_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_handle_timeout
void coap_dtls_handle_timeout(struct coap_session_t *coap_session)
Handle a DTLS timeout expiration.
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_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_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_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_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_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's default PSK information.
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_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_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_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's default Root CA information for a client or server.
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_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_session_update_mtu
void coap_dtls_session_update_mtu(struct coap_session_t *coap_session)
Notify of a change in the CoAP session's MTU, for example after a PMTU update.
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_free_context
void coap_dtls_free_context(void *dtls_context)
Releases the storage allocated for dtls_context.
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's default server PKI information.
COAP_DTLS_ROLE_SERVER
@ COAP_DTLS_ROLE_SERVER
Internal function invoked for server.
Definition: coap_dtls.h:268
COAP_DTLS_ROLE_CLIENT
@ COAP_DTLS_ROLE_CLIENT
Internal function invoked for client.
Definition: coap_dtls.h:267
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_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_dtls_key_t
struct coap_dtls_key_t coap_dtls_key_t
The structure that holds the PKI key information.
coap_tls_is_supported
int coap_tls_is_supported(void)
Check whether TLS is available.
Definition: coap_notls.c:26
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_pki_key_pem_t
struct coap_pki_key_pem_t coap_pki_key_pem_t
The structure that holds the PKI PEM definitions.
coap_pki_key_t
coap_pki_key_t
The enum used for determining the PKI key formats.
Definition: coap_dtls.h:133
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_dtls_is_supported
int coap_dtls_is_supported(void)
Check whether DTLS is available.
Definition: coap_notls.c:21
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_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_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_tls_library_t
coap_tls_library_t
Definition: coap_dtls.h:40
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_PKI_KEY_PEM
@ COAP_PKI_KEY_PEM
The PKI key type is PEM.
Definition: coap_dtls.h:134
COAP_PKI_KEY_ASN1
@ COAP_PKI_KEY_ASN1
The PKI key type is ASN.1 (DER)
Definition: coap_dtls.h:135
COAP_ASN1_PKEY_DH
@ COAP_ASN1_PKEY_DH
DH type.
Definition: coap_dtls.h:121
COAP_ASN1_PKEY_NONE
@ COAP_ASN1_PKEY_NONE
NONE.
Definition: coap_dtls.h:113
COAP_ASN1_PKEY_TLS1_PRF
@ COAP_ASN1_PKEY_TLS1_PRF
TLS1_PRF type.
Definition: coap_dtls.h:126
COAP_ASN1_PKEY_RSA2
@ COAP_ASN1_PKEY_RSA2
RSA2 type.
Definition: coap_dtls.h:115
COAP_ASN1_PKEY_DSA
@ COAP_ASN1_PKEY_DSA
DSA type.
Definition: coap_dtls.h:116
COAP_ASN1_PKEY_DHX
@ COAP_ASN1_PKEY_DHX
DHX type.
Definition: coap_dtls.h:122
COAP_ASN1_PKEY_DSA4
@ COAP_ASN1_PKEY_DSA4
DSA4 type.
Definition: coap_dtls.h:120
COAP_ASN1_PKEY_DSA2
@ COAP_ASN1_PKEY_DSA2
DSA2 type.
Definition: coap_dtls.h:118
COAP_ASN1_PKEY_RSA
@ COAP_ASN1_PKEY_RSA
RSA type.
Definition: coap_dtls.h:114
COAP_ASN1_PKEY_DSA1
@ COAP_ASN1_PKEY_DSA1
DSA1 type.
Definition: coap_dtls.h:117
COAP_ASN1_PKEY_HKDF
@ COAP_ASN1_PKEY_HKDF
HKDF type.
Definition: coap_dtls.h:127
COAP_ASN1_PKEY_EC
@ COAP_ASN1_PKEY_EC
EC type.
Definition: coap_dtls.h:123
COAP_ASN1_PKEY_DSA3
@ COAP_ASN1_PKEY_DSA3
DSA3 type.
Definition: coap_dtls.h:119
COAP_ASN1_PKEY_HMAC
@ COAP_ASN1_PKEY_HMAC
HMAC type.
Definition: coap_dtls.h:124
COAP_ASN1_PKEY_CMAC
@ COAP_ASN1_PKEY_CMAC
CMAC type.
Definition: coap_dtls.h:125
COAP_TLS_LIBRARY_GNUTLS
@ COAP_TLS_LIBRARY_GNUTLS
Using GnuTLS library.
Definition: coap_dtls.h:44
COAP_TLS_LIBRARY_TINYDTLS
@ COAP_TLS_LIBRARY_TINYDTLS
Using TinyDTLS library.
Definition: coap_dtls.h:42
COAP_TLS_LIBRARY_NOTLS
@ COAP_TLS_LIBRARY_NOTLS
No DTLS library.
Definition: coap_dtls.h:41
COAP_TLS_LIBRARY_OPENSSL
@ COAP_TLS_LIBRARY_OPENSSL
Using OpenSSL library.
Definition: coap_dtls.h:43
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_dtls_get_log_level
int coap_dtls_get_log_level(void)
Get the current (D)TLS logging.
Definition: coap_notls.c:79
coap_context_t
The CoAP stack's global state is stored in a coap_context_t object.
Definition: net.h:147
coap_dtls_key_t
The structure that holds the PKI key information.
Definition: coap_dtls.h:163
coap_dtls_key_t::pem
coap_pki_key_pem_t pem
for PEM keys
Definition: coap_dtls.h:166
coap_dtls_key_t::key
union coap_dtls_key_t::@1 key
coap_dtls_key_t::key_type
coap_pki_key_t key_type
key format type
Definition: coap_dtls.h:164
coap_dtls_key_t::asn1
coap_pki_key_asn1_t asn1
for ASN.1 (DER) keys
Definition: coap_dtls.h:167
coap_dtls_pki_t
The structure used for defining the PKI setup data to be used.
Definition: coap_dtls.h:193
coap_dtls_pki_t::allow_no_crl
uint8_t allow_no_crl
1 ignore if CRL not there
Definition: coap_dtls.h:204
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_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::cert_chain_validation
uint8_t cert_chain_validation
1 if to check cert_chain_verify_depth
Definition: coap_dtls.h:201
coap_dtls_pki_t::version
uint8_t version
Definition: coap_dtls.h:194
coap_dtls_pki_t::check_cert_revocation
uint8_t check_cert_revocation
1 if revocation checks wanted
Definition: coap_dtls.h:203
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_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,...
Definition: coap_dtls.h:236
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::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::client_sni
char * client_sni
If not NULL, SNI to use in client TLS setup.
Definition: coap_dtls.h:238
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_dtls_pki_t::allow_self_signed
uint8_t allow_self_signed
1 if self signed certs are allowed
Definition: coap_dtls.h:199
coap_dtls_pki_t::reserved
uint8_t reserved[6]
Reserved - must be set to 0 for future compatibility.
Definition: coap_dtls.h:206
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_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_dtls_pki_t::allow_expired_crl
uint8_t allow_expired_crl
1 if expired crl is allowed
Definition: coap_dtls.h:205
coap_dtls_pki_t::pki_key
coap_dtls_key_t pki_key
PKI key definition.
Definition: coap_dtls.h:242
coap_pki_key_asn1_t
The structure that holds the PKI ASN.1 (DER) definitions.
Definition: coap_dtls.h:150
coap_pki_key_asn1_t::private_key
const uint8_t * private_key
ASN1 (DER) Private Key.
Definition: coap_dtls.h:153
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_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::private_key_len
size_t private_key_len
ASN1 Private Key length.
Definition: coap_dtls.h:156
coap_pki_key_asn1_t::ca_cert
const uint8_t * ca_cert
ASN1 (DER) Common CA Cert.
Definition: coap_dtls.h:151
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_asn1_t::public_cert
const uint8_t * public_cert
ASN1 (DER) Public Cert.
Definition: coap_dtls.h:152
coap_pki_key_pem_t
The structure that holds the PKI PEM definitions.
Definition: coap_dtls.h:141
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_pem_t::public_cert
const char * public_cert
File location of Public Cert in PEM format.
Definition: coap_dtls.h:143
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_session_t
Definition: coap_session.h:59
coap_tls_version_t
The structure used for returning the underlying (D)TLS library information.
Definition: coap_dtls.h:51
coap_tls_version_t::built_version
uint64_t built_version
(D)TLS Built against Library Version
Definition: coap_dtls.h:54
coap_tls_version_t::type
coap_tls_library_t type
Library type.
Definition: coap_dtls.h:53
coap_tls_version_t::version
uint64_t version
(D)TLS runtime Library Version
Definition: coap_dtls.h:52
uint8_t
unsigned char uint8_t
Definition: uthash.h:79