libcoap  4.2.0rc4
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 #define COAP_DTLS_ROLE_CLIENT 0
265 #define COAP_DTLS_ROLE_SERVER 1
288 int
289 coap_dtls_context_set_psk(struct coap_context_t *coap_context,
290  const char *identity_hint,
291  int role);
292 
312 int
313 coap_dtls_context_set_pki(struct coap_context_t *coap_context,
314  coap_dtls_pki_t *setup_data,
315  int role);
316 
331 int
333  const char *ca_file,
334  const char *ca_dir);
335 
347 int coap_dtls_context_check_keys_enabled(struct coap_context_t *coap_context);
348 
356 void coap_dtls_free_context(void *dtls_context);
357 
368 void *coap_dtls_new_client_session(coap_session_t *coap_session);
369 
383 void *coap_dtls_new_server_session(coap_session_t *coap_session);
384 
393 void coap_dtls_free_session(coap_session_t *coap_session);
394 
403 void coap_dtls_session_update_mtu(coap_session_t *coap_session);
404 
417 int coap_dtls_send(coap_session_t *coap_session,
418  const uint8_t *data,
419  size_t data_len);
420 
430 
440 coap_tick_t coap_dtls_get_context_timeout(void *dtls_context);
441 
452 
460 void coap_dtls_handle_timeout(coap_session_t *coap_session);
461 
474 int coap_dtls_receive(coap_session_t *coap_session,
475  const uint8_t *data,
476  size_t data_len);
477 
492 int coap_dtls_hello(coap_session_t *coap_session,
493  const uint8_t *data,
494  size_t data_len);
495 
505 unsigned int coap_dtls_get_overhead(coap_session_t *coap_session);
506 
519 void *coap_tls_new_client_session(coap_session_t *coap_session, int *connected);
520 
533 void *coap_tls_new_server_session(coap_session_t *coap_session, int *connected);
534 
543 void coap_tls_free_session( coap_session_t *coap_session );
544 
557 ssize_t coap_tls_write(coap_session_t *coap_session,
558  const uint8_t *data,
559  size_t data_len
560  );
561 
574 ssize_t coap_tls_read(coap_session_t *coap_session,
575  uint8_t *data,
576  size_t data_len
577  );
578 
585 void coap_dtls_startup(void);
586 
596 void coap_dtls_set_log_level(int level);
597 
604 int coap_dtls_get_log_level(void);
605 
606 
607 #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_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:125
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
RSA2 type.
Definition: coap_dtls.h:113
coap_dtls_sni_callback_t validate_sni_call_back
SNI check call-back function.
Definition: coap_dtls.h:226
HMAC type.
Definition: coap_dtls.h:122
DSA1 type.
Definition: coap_dtls.h:115
DSA type.
Definition: coap_dtls.h:114
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: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&#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: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
RSA type.
Definition: coap_dtls.h:112
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:118
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.
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.
const uint8_t * private_key
ASN1 (DER) Private Key.
Definition: coap_dtls.h:151
DSA3 type.
Definition: coap_dtls.h:117
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&#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: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
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: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
DSA2 type.
Definition: coap_dtls.h:116
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
DHX type.
Definition: coap_dtls.h:120
uint64_t built_version
(D)TLS Built against Library Version
Definition: coap_dtls.h:50
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:123
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&#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: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