libcoap  4.2.0
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;
50  uint64_t built_version;
52 
59 
60 struct coap_dtls_pki_t;
61 
77 typedef int (*coap_dtls_security_setup_t)(void* tls_session,
78  struct coap_dtls_pki_t *setup_data);
79 
98 typedef int (*coap_dtls_cn_callback_t)(const char *cn,
99  const uint8_t *asn1_public_cert,
100  size_t asn1_length,
101  coap_session_t *coap_session,
102  unsigned depth,
103  int validated,
104  void *arg);
105 
127 
131 typedef enum coap_pki_key_t {
135 
139 typedef struct coap_pki_key_pem_t {
140  const char *ca_file;
141  const char *public_cert;
142  const char *private_key;
144 
148 typedef struct coap_pki_key_asn1_t {
149  const uint8_t *ca_cert;
152  size_t ca_cert_len;
157 
161 typedef struct coap_dtls_key_t {
163  union {
166  } key;
168 
182 typedef coap_dtls_key_t *(*coap_dtls_sni_callback_t)(const char *sni,
183  void* arg);
184 
185 
186 #define COAP_DTLS_PKI_SETUP_VERSION 1
191 typedef struct coap_dtls_pki_t {
194  /* Options to enable different TLS functionality in libcoap */
204  uint8_t reserved[6];
206  /* Size of 6 chosen to align to next
207  * parameter, so if newly defined option
208  * it can use one of the reserverd slot so
209  * no need to change
210  * COAP_DTLS_PKI_SETUP_VERSION and just
211  * decrement the reserved[] count.
212  */
213 
235 
236  char* client_sni;
242 
261 void *
262 coap_dtls_new_context(struct coap_context_t *coap_context);
263 
264 typedef enum coap_dtls_role_t {
268 
290 int
291 coap_dtls_context_set_psk(struct coap_context_t *coap_context,
292  const char *identity_hint,
293  coap_dtls_role_t role);
294 
314 int
315 coap_dtls_context_set_pki(struct coap_context_t *coap_context,
316  coap_dtls_pki_t *setup_data,
317  coap_dtls_role_t role);
318 
333 int
335  const char *ca_file,
336  const char *ca_dir);
337 
349 int coap_dtls_context_check_keys_enabled(struct coap_context_t *coap_context);
350 
358 void coap_dtls_free_context(void *dtls_context);
359 
370 void *coap_dtls_new_client_session(coap_session_t *coap_session);
371 
385 void *coap_dtls_new_server_session(coap_session_t *coap_session);
386 
395 void coap_dtls_free_session(coap_session_t *coap_session);
396 
405 void coap_dtls_session_update_mtu(coap_session_t *coap_session);
406 
419 int coap_dtls_send(coap_session_t *coap_session,
420  const uint8_t *data,
421  size_t data_len);
422 
432 
442 coap_tick_t coap_dtls_get_context_timeout(void *dtls_context);
443 
454 
462 void coap_dtls_handle_timeout(coap_session_t *coap_session);
463 
476 int coap_dtls_receive(coap_session_t *coap_session,
477  const uint8_t *data,
478  size_t data_len);
479 
494 int coap_dtls_hello(coap_session_t *coap_session,
495  const uint8_t *data,
496  size_t data_len);
497 
507 unsigned int coap_dtls_get_overhead(coap_session_t *coap_session);
508 
521 void *coap_tls_new_client_session(coap_session_t *coap_session, int *connected);
522 
535 void *coap_tls_new_server_session(coap_session_t *coap_session, int *connected);
536 
545 void coap_tls_free_session( coap_session_t *coap_session );
546 
559 ssize_t coap_tls_write(coap_session_t *coap_session,
560  const uint8_t *data,
561  size_t data_len
562  );
563 
576 ssize_t coap_tls_read(coap_session_t *coap_session,
577  uint8_t *data,
578  size_t data_len
579  );
580 
587 void coap_dtls_startup(void);
588 
598 void coap_dtls_set_log_level(int level);
599 
606 int coap_dtls_get_log_level(void);
607 
608 
609 #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:197
The PKI key type is ASN.1 (DER)
Definition: coap_dtls.h:133
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:162
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:192
int coap_dtls_get_log_level(void)
Get the current (D)TLS logging.
Definition: coap_notls.c:81
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.
Internal function invoked for server.
Definition: coap_dtls.h:266
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.
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:227
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:195
uint8_t allow_no_crl
1 ignore if CRL not there
Definition: coap_dtls.h:202
uint64_t version
(D)TLS runtime Library Version
Definition: coap_dtls.h:48
coap_dtls_sni_callback_t validate_sni_call_back
SNI check call-back function.
Definition: coap_dtls.h:226
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:234
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:142
int type
Library type.
Definition: coap_dtls.h:49
uint8_t require_peer_cert
1 if peer cert is required
Definition: coap_dtls.h:196
coap_dtls_key_t pki_key
PKI key definition.
Definition: coap_dtls.h:240
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:98
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:164
char * client_sni
If not NULL, SNI to use in client TLS setup.
Definition: coap_dtls.h:236
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.
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:161
const uint8_t * public_cert
ASN1 (DER) Public Cert.
Definition: coap_dtls.h:150
const char * ca_file
File location of Common CA in PEM format.
Definition: coap_dtls.h:140
size_t ca_cert_len
ASN1 CA Cert length.
Definition: coap_dtls.h:152
The PKI key type is PEM.
Definition: coap_dtls.h:132
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...
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:199
struct coap_pki_key_asn1_t coap_pki_key_asn1_t
The structure that holds the PKI ASN.1 (DER) definitions.
union coap_dtls_key_t::@1 key
The structure that holds the PKI PEM definitions.
Definition: coap_dtls.h:139
coap_tick_t coap_dtls_get_timeout(coap_session_t *coap_session)
Get next timeout for this session.
Internal function invoked for client.
Definition: coap_dtls.h:265
const uint8_t * private_key
ASN1 (DER) Private Key.
Definition: coap_dtls.h:151
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:77
void coap_dtls_session_update_mtu(coap_session_t *coap_session)
Notify of a change in the CoAP session'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:218
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:198
uint8_t check_cert_revocation
1 if revocation checks wanted
Definition: coap_dtls.h:201
coap_dtls_role_t
Definition: coap_dtls.h:264
Pre-defined constants that reflect defaults for CoAP.
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:219
coap_asn1_privatekey_type_t
The enum used for determining the provided PKI ASN.1 (DER) Private Key formats.
Definition: coap_dtls.h:110
uint8_t allow_expired_crl
1 if expired crl is allowed
Definition: coap_dtls.h:203
The structure used for defining the PKI setup data to be used.
Definition: coap_dtls.h:191
coap_asn1_privatekey_type_t private_key_type
Private Key Type.
Definition: coap_dtls.h:155
uint8_t cert_chain_verify_depth
recommended depth is 3
Definition: coap_dtls.h:200
const char * public_cert
File location of Public Cert in PEM format.
Definition: coap_dtls.h:141
void coap_dtls_startup(void)
Initialize the underlying (D)TLS Library layer.
Definition: coap_notls.c:72
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:149
unsigned char uint8_t
Definition: uthash.h:79
TLS1_PRF type.
Definition: coap_dtls.h:124
size_t public_cert_len
ASN1 Public Cert length.
Definition: coap_dtls.h:153
The structure that holds the PKI ASN.1 (DER) definitions.
Definition: coap_dtls.h:148
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.
uint64_t built_version
(D)TLS Built against Library Version
Definition: coap_dtls.h:50
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:182
The CoAP stack'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:154
coap_pki_key_t
The enum used for determining the PKI key formats.
Definition: coap_dtls.h:131
coap_pki_key_asn1_t asn1
for ASN.1 (DER) keys
Definition: coap_dtls.h:165