libcoap  4.2.0rc2
coap_dtls.h
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 <bergmann@tzi.org>
5  * Copyright (C) 2017 Jean-Claude Michelou <jcm@spinetix.com>
6  *
7  * This file is part of the CoAP library libcoap. Please see README for terms
8  * of use.
9  */
10 
11 #ifndef _COAP_DTLS_H_
12 #define _COAP_DTLS_H_
13 
14 #include "net.h"
15 #include "coap_session.h"
16 #include "pdu.h"
17 
29 int coap_dtls_is_supported(void);
30 
36 int coap_tls_is_supported(void);
37 
38 #define COAP_TLS_LIBRARY_NOTLS 0
39 #define COAP_TLS_LIBRARY_TINYDTLS 1
40 #define COAP_TLS_LIBRARY_OPENSSL 2
41 #define COAP_TLS_LIBRARY_GNUTLS 3
47 typedef struct coap_tls_version_t {
48  uint64_t version;
49  int type;
51 
58 
59 struct coap_dtls_pki_t;
60 
76 typedef int (*coap_dtls_security_setup_t)(void* tls_session,
77  struct coap_dtls_pki_t *setup_data);
78 
97 typedef int (*coap_dtls_cn_callback_t)(const char *cn,
98  const uint8_t *asn1_public_cert,
99  size_t asn1_length,
100  coap_session_t *coap_session,
101  unsigned depth,
102  int validated,
103  void *arg);
104 
126 
130 typedef enum coap_pki_key_t {
134 
138 typedef struct coap_pki_key_pem_t {
139  const char *ca_file;
140  const char *public_cert;
141  const char *private_key;
143 
147 typedef struct coap_pki_key_asn1_t {
148  const uint8_t *ca_cert;
151  size_t ca_cert_len;
156 
160 typedef struct coap_dtls_key_t {
162  union {
165  } key;
167 
181 typedef coap_dtls_key_t *(*coap_dtls_sni_callback_t)(const char *sni,
182  void* arg);
183 
184 
185 #define COAP_DTLS_PKI_SETUP_VERSION 1
190 typedef struct coap_dtls_pki_t {
193  /* Options to enable different TLS functionality in libcoap */
203  uint8_t reserved[6];
205  /* Size of 6 chosen to align to next
206  * parameter, so if newly defined option
207  * it can use one of the reserverd slot so
208  * no need to change
209  * COAP_DTLS_PKI_SETUP_VERSION and just
210  * decrement the reserved[] count.
211  */
212 
234 
235  char* client_sni;
241 
260 void *
261 coap_dtls_new_context(struct coap_context_t *coap_context);
262 
263 #define COAP_DTLS_ROLE_CLIENT 0
264 #define COAP_DTLS_ROLE_SERVER 1
287 int
288 coap_dtls_context_set_psk(struct coap_context_t *coap_context,
289  const char *identity_hint,
290  int role);
291 
311 int
312 coap_dtls_context_set_pki(struct coap_context_t *coap_context,
313  coap_dtls_pki_t *setup_data,
314  int role);
315 
330 int
332  const char *ca_file,
333  const char *ca_dir);
334 
346 int coap_dtls_context_check_keys_enabled(struct coap_context_t *coap_context);
347 
355 void coap_dtls_free_context(void *dtls_context);
356 
367 void *coap_dtls_new_client_session(coap_session_t *coap_session);
368 
382 void *coap_dtls_new_server_session(coap_session_t *coap_session);
383 
392 void coap_dtls_free_session(coap_session_t *coap_session);
393 
402 void coap_dtls_session_update_mtu(coap_session_t *coap_session);
403 
416 int coap_dtls_send(coap_session_t *coap_session,
417  const uint8_t *data,
418  size_t data_len);
419 
429 
439 coap_tick_t coap_dtls_get_context_timeout(void *dtls_context);
440 
451 
459 void coap_dtls_handle_timeout(coap_session_t *coap_session);
460 
473 int coap_dtls_receive(coap_session_t *coap_session,
474  const uint8_t *data,
475  size_t data_len);
476 
491 int coap_dtls_hello(coap_session_t *coap_session,
492  const uint8_t *data,
493  size_t data_len);
494 
504 unsigned int coap_dtls_get_overhead(coap_session_t *coap_session);
505 
518 void *coap_tls_new_client_session(coap_session_t *coap_session, int *connected);
519 
532 void *coap_tls_new_server_session(coap_session_t *coap_session, int *connected);
533 
542 void coap_tls_free_session( coap_session_t *coap_session );
543 
556 ssize_t coap_tls_write(coap_session_t *coap_session,
557  const uint8_t *data,
558  size_t data_len
559  );
560 
573 ssize_t coap_tls_read(coap_session_t *coap_session,
574  uint8_t *data,
575  size_t data_len
576  );
577 
584 void coap_dtls_startup(void);
585 
595 void coap_dtls_set_log_level(int level);
596 
603 int coap_dtls_get_log_level(void);
604 
605 
606 #endif /* COAP_DTLS_H */
void coap_dtls_set_log_level(int level)
Sets the (D)TLS logging level to the specified level.
Definition: coap_notls.c:76
void coap_tls_free_session(coap_session_t *coap_session)
Terminates the TLS session (may send an ALERT if necessary) then frees the underlying TLS library obj...
void coap_dtls_free_context(void *dtls_context)
Releases the storage allocated for dtls_context.
ssize_t coap_tls_read(coap_session_t *coap_session, uint8_t *data, size_t data_len)
Read some data from a TLS peer.
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:196
The PKI key type is ASN.1 (DER)
Definition: coap_dtls.h:132
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:161
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:191
int coap_dtls_get_log_level(void)
Get the current (D)TLS logging.
Definition: coap_notls.c:81
int coap_dtls_hello(coap_session_t *coap_session, const uint8_t *data, size_t data_len)
Handling client HELLO messages from a new candiate peer.
HKDF type.
Definition: coap_dtls.h:124
int coap_dtls_is_supported(void)
Check whether DTLS is available.
Definition: coap_notls.c:23
void * sni_call_back_arg
Passed in to the sni call-back function.
Definition: coap_dtls.h:226
struct coap_tls_version_t coap_tls_version_t
The structure used for returning the underlying (D)TLS library information.
void coap_dtls_handle_timeout(coap_session_t *coap_session)
Handle a DTLS timeout expiration.
uint8_t verify_peer_cert
Set to 1 to support this version of the struct.
Definition: coap_dtls.h:194
uint8_t allow_no_crl
1 ignore if CRL not there
Definition: coap_dtls.h:201
uint64_t version
(D)TLS Library Version
Definition: coap_dtls.h:48
RSA2 type.
Definition: coap_dtls.h:112
coap_dtls_sni_callback_t validate_sni_call_back
SNI check call-back function.
Definition: coap_dtls.h:225
HMAC type.
Definition: coap_dtls.h:121
DSA1 type.
Definition: coap_dtls.h:114
DSA type.
Definition: coap_dtls.h:113
coap_dtls_security_setup_t additional_tls_setup_call_back
Addtional 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:233
int coap_tls_is_supported(void)
Check whether TLS is available.
Definition: coap_notls.c:28
void * coap_dtls_new_client_session(coap_session_t *coap_session)
Create a new client-side 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:33
int coap_dtls_send(coap_session_t *coap_session, const uint8_t *data, size_t data_len)
Send data to a DTLS peer.
const char * private_key
File location of Private Key in PEM format.
Definition: coap_dtls.h:141
int type
Library type.
Definition: coap_dtls.h:49
uint8_t require_peer_cert
1 if peer cert is required
Definition: coap_dtls.h:195
coap_dtls_key_t pki_key
PKI key definition.
Definition: coap_dtls.h:239
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().
Definition: coap_dtls.h:97
int coap_dtls_receive(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 pem
for PEM keys
Definition: coap_dtls.h:163
char * client_sni
If not NULL, SNI to use in client TLS setup.
Definition: coap_dtls.h:235
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:85
The structure that holds the PKI key information.
Definition: coap_dtls.h:160
const uint8_t * public_cert
ASN1 (DER) Public Cert.
Definition: coap_dtls.h:149
const char * ca_file
File location of Common CA in PEM format.
Definition: coap_dtls.h:139
size_t ca_cert_len
ASN1 CA Cert length.
Definition: coap_dtls.h:151
The PKI key type is PEM.
Definition: coap_dtls.h:131
RSA type.
Definition: coap_dtls.h:111
The structure used for returning the underlying (D)TLS library information.
Definition: coap_dtls.h:47
void coap_dtls_free_session(coap_session_t *coap_session)
Terminates the DTLS session (may send an ALERT if necessary) then frees the underlying TLS library ob...
DSA4 type.
Definition: coap_dtls.h:117
void * coap_tls_new_client_session(coap_session_t *coap_session, int *connected)
Create a new TLS client-side session.
uint8_t cert_chain_validation
1 if to check cert_chain_verify_depth
Definition: coap_dtls.h:198
struct coap_pki_key_asn1_t coap_pki_key_asn1_t
The structure that holds the PKI ASN.1 (DER) definitions.
The structure that holds the PKI PEM definitions.
Definition: coap_dtls.h:138
coap_tick_t coap_dtls_get_timeout(coap_session_t *coap_session)
Get next timeout for this session.
const uint8_t * private_key
ASN1 (DER) Private Key.
Definition: coap_dtls.h:150
DSA3 type.
Definition: coap_dtls.h:116
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:76
void coap_dtls_session_update_mtu(coap_session_t *coap_session)
Notify of a change in the CoAP session&#39;s MTU, for example after a PMTU update.
coap_dtls_cn_callback_t validate_cn_call_back
CN check call-back function.
Definition: coap_dtls.h:217
ssize_t coap_tls_write(coap_session_t *coap_session, const uint8_t *data, size_t data_len)
Send data to a TLS peer, with implicit flush.
uint8_t allow_expired_certs
1 if expired certs are allowed
Definition: coap_dtls.h:197
uint8_t check_cert_revocation
1 if revocation checks wanted
Definition: coap_dtls.h:200
Pre-defined constants that reflect defaults for CoAP.
int coap_dtls_context_set_psk(struct coap_context_t *coap_context, const char *identity_hint, int role)
Set the DTLS context&#39;s default PSK information.
coap_tick_t coap_dtls_get_context_timeout(void *dtls_context)
Do all pending retransmits and get next timeout.
unsigned int coap_dtls_get_overhead(coap_session_t *coap_session)
Get DTLS overhead over cleartext PDUs.
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:218
coap_asn1_privatekey_type_t
The enum used for determining the provided PKI ASN.1 (DER) Private Key formats.
Definition: coap_dtls.h:109
uint8_t allow_expired_crl
1 if expired crl is allowed
Definition: coap_dtls.h:202
The structure used for defining the PKI setup data to be used.
Definition: coap_dtls.h:190
coap_asn1_privatekey_type_t private_key_type
Private Key Type.
Definition: coap_dtls.h:154
uint8_t cert_chain_verify_depth
recommended depth is 3
Definition: coap_dtls.h:199
const char * public_cert
File location of Public Cert in PEM format.
Definition: coap_dtls.h:140
void coap_dtls_startup(void)
Initialize the underlying (D)TLS Library layer.
Definition: coap_notls.c:72
DSA2 type.
Definition: coap_dtls.h:115
void * coap_tls_new_server_session(coap_session_t *coap_session, int *connected)
Create a TLS new server-side session.
const uint8_t * ca_cert
ASN1 (DER) Common CA Cert.
Definition: coap_dtls.h:148
unsigned char uint8_t
Definition: uthash.h:79
TLS1_PRF type.
Definition: coap_dtls.h:123
size_t public_cert_len
ASN1 Public Cert length.
Definition: coap_dtls.h:152
The structure that holds the PKI ASN.1 (DER) definitions.
Definition: coap_dtls.h:147
DHX type.
Definition: coap_dtls.h:119
int coap_dtls_context_set_pki(struct coap_context_t *coap_context, coap_dtls_pki_t *setup_data, int role)
Set the DTLS context&#39;s default server PKI information.
CMAC type.
Definition: coap_dtls.h:122
void * coap_dtls_new_server_session(coap_session_t *coap_session)
Create a new DTLS server-side session.
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:181
The CoAP stack&#39;s global state is stored in a coap_context_t object.
Definition: net.h:148
int coap_dtls_is_context_timeout(void)
Check if timeout is handled per CoAP session or per CoAP context.
Definition: coap_notls.c:116
size_t private_key_len
ASN1 Private Key length.
Definition: coap_dtls.h:153
coap_pki_key_t
The enum used for determining the PKI key formats.
Definition: coap_dtls.h:130
coap_pki_key_asn1_t asn1
for ASN.1 (DER) keys
Definition: coap_dtls.h:164