libcoap  4.2.1
Go to the documentation of this file.
1 /*
2  * coap_dtls.h -- (Datagram) Transport Layer Support for libcoap
3  *
4  * Copyright (C) 2016 Olaf Bergmann <>
5  * Copyright (C) 2017 Jean-Claude Michelou <>
6  *
7  * This file is part of the CoAP library libcoap. Please see README for terms
8  * of use.
9  */
11 #ifndef COAP_DTLS_H_
12 #define COAP_DTLS_H_
14 #include "coap_time.h"
16 struct coap_context_t;
17 struct coap_session_t;
18 struct coap_dtls_pki_t;
31 int coap_dtls_is_supported(void);
38 int coap_tls_is_supported(void);
40 typedef enum coap_tls_library_t {
51 typedef struct coap_tls_version_t {
52  uint64_t version;
54  uint64_t built_version;
79 typedef int (*coap_dtls_security_setup_t)(void* tls_session,
80  struct coap_dtls_pki_t *setup_data);
100 typedef int (*coap_dtls_cn_callback_t)(const char *cn,
101  const uint8_t *asn1_public_cert,
102  size_t asn1_length,
103  struct coap_session_t *coap_session,
104  unsigned depth,
105  int validated,
106  void *arg);
133 typedef enum coap_pki_key_t {
141 typedef struct coap_pki_key_pem_t {
142  const char *ca_file;
143  const char *public_cert;
144  const char *private_key;
150 typedef struct coap_pki_key_asn1_t {
151  const uint8_t *ca_cert;
154  size_t ca_cert_len;
163 typedef struct coap_dtls_key_t {
165  union {
168  } key;
184 typedef coap_dtls_key_t *(*coap_dtls_sni_callback_t)(const char *sni,
185  void* arg);
193 typedef struct coap_dtls_pki_t {
196  /* Options to enable different TLS functionality in libcoap */
206  uint8_t reserved[6];
208  /* Size of 6 chosen to align to next
209  * parameter, so if newly defined option
210  * it can use one of the reserverd slot so
211  * no need to change
213  * decrement the reserved[] count.
214  */
238  char* client_sni;
263 void *
264 coap_dtls_new_context(struct coap_context_t *coap_context);
266 typedef enum coap_dtls_role_t {
292 int
293 coap_dtls_context_set_psk(struct coap_context_t *coap_context,
294  const char *identity_hint,
295  coap_dtls_role_t role);
316 int
317 coap_dtls_context_set_pki(struct coap_context_t *coap_context,
318  coap_dtls_pki_t *setup_data,
319  coap_dtls_role_t role);
335 int
337  const char *ca_file,
338  const char *ca_dir);
351 int coap_dtls_context_check_keys_enabled(struct coap_context_t *coap_context);
360 void coap_dtls_free_context(void *dtls_context);
372 void *coap_dtls_new_client_session(struct coap_session_t *coap_session);
387 void *coap_dtls_new_server_session(struct coap_session_t *coap_session);
397 void coap_dtls_free_session(struct coap_session_t *coap_session);
407 void coap_dtls_session_update_mtu(struct coap_session_t *coap_session);
421 int coap_dtls_send(struct coap_session_t *coap_session,
422  const uint8_t *data,
423  size_t data_len);
444 coap_tick_t coap_dtls_get_context_timeout(void *dtls_context);
457  coap_tick_t now);
466 void coap_dtls_handle_timeout(struct coap_session_t *coap_session);
480 int coap_dtls_receive(struct coap_session_t *coap_session,
481  const uint8_t *data,
482  size_t data_len);
498 int coap_dtls_hello(struct coap_session_t *coap_session,
499  const uint8_t *data,
500  size_t data_len);
511 unsigned int coap_dtls_get_overhead(struct coap_session_t *coap_session);
525 void *coap_tls_new_client_session(struct coap_session_t *coap_session, int *connected);
539 void *coap_tls_new_server_session(struct coap_session_t *coap_session, int *connected);
549 void coap_tls_free_session( struct coap_session_t *coap_session );
563 ssize_t coap_tls_write(struct coap_session_t *coap_session,
564  const uint8_t *data,
565  size_t data_len
566  );
580 ssize_t coap_tls_read(struct coap_session_t *coap_session,
581  uint8_t *data,
582  size_t data_len
583  );
591 void coap_dtls_startup(void);
602 void coap_dtls_set_log_level(int level);
610 int coap_dtls_get_log_level(void);
613 #endif /* COAP_DTLS_H */
void coap_dtls_set_log_level(int level)
Sets the (D)TLS logging level to the specified level.
void coap_dtls_free_context(void *dtls_context)
Releases the storage allocated for dtls_context.
Using TinyDTLS library.
Definition: coap_dtls.h:42
struct coap_pki_key_pem_t coap_pki_key_pem_t
The structure that holds the PKI PEM definitions.
uint8_t allow_self_signed
1 if self signed certs are allowed
Definition: coap_dtls.h:199
The PKI key type is ASN.1 (DER)
Definition: coap_dtls.h:135
void * coap_dtls_new_context(struct coap_context_t *coap_context)
Creates a new DTLS context for the given coap_context.
coap_pki_key_t key_type
key format type
Definition: coap_dtls.h:164
struct coap_dtls_pki_t coap_dtls_pki_t
The structure used for defining the PKI setup data to be used.
uint8_t version
Definition: coap_dtls.h:194
int coap_dtls_get_log_level(void)
Get the current (D)TLS logging.
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.
Clock Handling.
Internal function invoked for server.
Definition: coap_dtls.h:268
HKDF type.
Definition: coap_dtls.h:127
int coap_dtls_is_supported(void)
Check whether DTLS is available.
void * sni_call_back_arg
Passed in to the sni call-back function.
Definition: coap_dtls.h:229
struct coap_tls_version_t coap_tls_version_t
The structure used for returning the underlying (D)TLS library information.
uint8_t verify_peer_cert
Set to 1 to support this version of the struct.
Definition: coap_dtls.h:197
uint8_t allow_no_crl
1 ignore if CRL not there
Definition: coap_dtls.h:204
uint64_t version
(D)TLS runtime Library Version
Definition: coap_dtls.h:52
void * coap_tls_new_server_session(struct coap_session_t *coap_session, int *connected)
Create a TLS new server-side session.
void * coap_dtls_new_client_session(struct coap_session_t *coap_session)
Create a new client-side session.
void * coap_tls_new_client_session(struct coap_session_t *coap_session, int *connected)
Create a new TLS client-side session.
RSA2 type.
Definition: coap_dtls.h:115
coap_dtls_sni_callback_t validate_sni_call_back
SNI check call-back function.
Definition: coap_dtls.h:228
HMAC type.
Definition: coap_dtls.h:124
DSA1 type.
Definition: coap_dtls.h:117
DSA type.
Definition: coap_dtls.h:116
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
No DTLS library.
Definition: coap_dtls.h:41
int coap_tls_is_supported(void)
Check whether TLS is available.
Definition: coap_notls.c:26
Definition: coap_dtls.h:40
void * coap_dtls_new_server_session(struct coap_session_t *coap_session)
Create a new DTLS server-side session.
coap_tls_library_t type
Library type.
Definition: coap_dtls.h:53
coap_tick_t coap_dtls_get_timeout(struct coap_session_t *coap_session, coap_tick_t now)
Get next timeout for this session.
struct coap_dtls_key_t coap_dtls_key_t
The structure that holds the PKI key information.
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
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.
const char * private_key
File location of Private Key in PEM format.
Definition: coap_dtls.h:144
uint8_t require_peer_cert
1 if peer cert is required
Definition: coap_dtls.h:198
coap_dtls_key_t pki_key
PKI key definition.
Definition: coap_dtls.h:242
coap_pki_key_pem_t pem
for PEM keys
Definition: coap_dtls.h:166
char * client_sni
If not NULL, SNI to use in client TLS setup.
Definition: coap_dtls.h:238
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.
uint64_t coap_tick_t
This data type represents internal timer ticks with COAP_TICKS_PER_SECOND resolution.
Definition: coap_time.h:93
The structure that holds the PKI key information.
Definition: coap_dtls.h:163
const uint8_t * public_cert
ASN1 (DER) Public Cert.
Definition: coap_dtls.h:152
const char * ca_file
File location of Common CA in PEM format.
Definition: coap_dtls.h:142
size_t ca_cert_len
ASN1 CA Cert length.
Definition: coap_dtls.h:154
The PKI key type is PEM.
Definition: coap_dtls.h:134
RSA type.
Definition: coap_dtls.h:114
The structure used for returning the underlying (D)TLS library information.
Definition: coap_dtls.h:51
DSA4 type.
Definition: coap_dtls.h:120
uint8_t cert_chain_validation
1 if to check cert_chain_verify_depth
Definition: coap_dtls.h:201
struct coap_pki_key_asn1_t coap_pki_key_asn1_t
The structure that holds the PKI ASN.1 (DER) definitions.
Using OpenSSL library.
Definition: coap_dtls.h:43
The structure that holds the PKI PEM definitions.
Definition: coap_dtls.h:141
Internal function invoked for client.
Definition: coap_dtls.h:267
const uint8_t * private_key
ASN1 (DER) Private Key.
Definition: coap_dtls.h:153
DSA3 type.
Definition: coap_dtls.h:119
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_cn_callback_t validate_cn_call_back
CN check call-back function.
Definition: coap_dtls.h:220
Using GnuTLS library.
Definition: coap_dtls.h:44
unsigned int coap_dtls_get_overhead(struct coap_session_t *coap_session)
Get DTLS overhead over cleartext PDUs.
uint8_t allow_expired_certs
1 if expired certs are allowed
Definition: coap_dtls.h:200
uint8_t check_cert_revocation
1 if revocation checks wanted
Definition: coap_dtls.h:203
Definition: coap_dtls.h:266
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.
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_tick_t coap_dtls_get_context_timeout(void *dtls_context)
Do all pending retransmits and get next timeout.
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.
void * cn_call_back_arg
Passed in to the CN call-back function.
Definition: coap_dtls.h:221
The enum used for determining the provided PKI ASN.1 (DER) Private Key formats.
Definition: coap_dtls.h:112
uint8_t allow_expired_crl
1 if expired crl is allowed
Definition: coap_dtls.h:205
void coap_dtls_handle_timeout(struct coap_session_t *coap_session)
Handle a DTLS timeout expiration.
The structure used for defining the PKI setup data to be used.
Definition: coap_dtls.h:193
coap_asn1_privatekey_type_t private_key_type
Private Key Type.
Definition: coap_dtls.h:157
uint8_t cert_chain_verify_depth
recommended depth is 3
Definition: coap_dtls.h:202
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...
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.
const char * public_cert
File location of Public Cert in PEM format.
Definition: coap_dtls.h:143
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.
void coap_dtls_startup(void)
Initialize the underlying (D)TLS Library layer.
Definition: coap_notls.c:70
DSA2 type.
Definition: coap_dtls.h:118
const uint8_t * ca_cert
ASN1 (DER) Common CA Cert.
Definition: coap_dtls.h:151
unsigned char uint8_t
Definition: uthash.h:79
TLS1_PRF type.
Definition: coap_dtls.h:126
int coap_dtls_send(struct coap_session_t *coap_session, const uint8_t *data, size_t data_len)
Send data to a DTLS peer.
size_t public_cert_len
ASN1 Public Cert length.
Definition: coap_dtls.h:155
The structure that holds the PKI ASN.1 (DER) definitions.
Definition: coap_dtls.h:150
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.
DHX type.
Definition: coap_dtls.h:122
uint64_t built_version
(D)TLS Built against Library Version
Definition: coap_dtls.h:54
CMAC type.
Definition: coap_dtls.h:125
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_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
The CoAP stack&#39;s global state is stored in a coap_context_t object.
Definition: net.h:147
int coap_dtls_is_context_timeout(void)
Check if timeout is handled per CoAP session or per CoAP context.
Definition: coap_notls.c:114
size_t private_key_len
ASN1 Private Key length.
Definition: coap_dtls.h:156
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
The enum used for determining the PKI key formats.
Definition: coap_dtls.h:133
coap_pki_key_asn1_t asn1
for ASN.1 (DER) keys
Definition: coap_dtls.h:167