libcoap  4.3.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 "coap_time.h"
15 #include "str.h"
16 
23 #ifndef COAP_DTLS_HINT_LENGTH
24 #define COAP_DTLS_HINT_LENGTH 128
25 #endif
26 
27 typedef enum coap_dtls_role_t {
31 
32 #define COAP_DTLS_RPK_CERT_CN "RPK"
33 
39 int coap_dtls_is_supported(void);
40 
46 int coap_tls_is_supported(void);
47 
48 typedef enum coap_tls_library_t {
55 
60 typedef struct coap_tls_version_t {
61  uint64_t version;
63  uint64_t built_version;
65 
72 
88 typedef int (*coap_dtls_security_setup_t)(void* tls_session,
89  struct coap_dtls_pki_t *setup_data);
90 
111 typedef int (*coap_dtls_cn_callback_t)(const char *cn,
112  const uint8_t *asn1_public_cert,
113  size_t asn1_length,
114  coap_session_t *coap_session,
115  unsigned int depth,
116  int validated,
117  void *arg);
118 
140 
144 typedef enum coap_pki_key_t {
150 
154 typedef struct coap_pki_key_pem_t {
155  const char *ca_file;
156  const char *public_cert;
157  const char *private_key;
159 
169 typedef struct coap_pki_key_pem_buf_t {
170  const uint8_t *ca_cert;
171  const uint8_t *public_cert;
172  const uint8_t *private_key;
175  size_t ca_cert_len;
179 
183 typedef struct coap_pki_key_asn1_t {
184  const uint8_t *ca_cert;
185  const uint8_t *public_cert;
186  const uint8_t *private_key;
187  size_t ca_cert_len;
192 
196 typedef struct coap_pki_key_pkcs11_t {
197  const char *ca;
198  const char *public_cert;
199  const char *private_key;
200  const char *user_pin;
204 
208 typedef struct coap_dtls_key_t {
210  union {
215  } key;
217 
231 typedef coap_dtls_key_t *(*coap_dtls_pki_sni_callback_t)(const char *sni,
232  void* arg);
233 
234 
235 #define COAP_DTLS_PKI_SETUP_VERSION 1
240 typedef struct coap_dtls_pki_t {
241  uint8_t version;
244  /* Options to enable different TLS functionality in libcoap */
246  uint8_t check_common_ca;
254  uint8_t allow_no_crl;
258  uint8_t is_rpk_not_cert;
261  uint8_t reserved[3];
263  /* Size of 3 chosen to align to next
264  * parameter, so if newly defined option
265  * it can use one of the reserverd slot so
266  * no need to change
267  * COAP_DTLS_PKI_SETUP_VERSION and just
268  * decrement the reserved[] count.
269  */
270 
292 
293  char* client_sni;
299 
303 typedef struct coap_dtls_cpsk_info_t {
307 
324 typedef const coap_dtls_cpsk_info_t *(*coap_dtls_ih_callback_t)(
325  struct coap_str_const_t *hint,
326  coap_session_t *coap_session,
327  void *arg);
328 
329 #define COAP_DTLS_CPSK_SETUP_VERSION 1
334 typedef struct coap_dtls_cpsk_t {
335  uint8_t version;
338  /* Options to enable different TLS functionality in libcoap */
339  uint8_t reserved[7];
341  /* Size of 7 chosen to align to next
342  * parameter, so if newly defined option
343  * it can use one of the reserverd slot so
344  * no need to change
345  * COAP_DTLS_CPSK_SETUP_VERSION and just
346  * decrement the reserved[] count.
347  */
348 
358  char* client_sni;
365 
370 typedef struct coap_dtls_spsk_info_t {
374 
375 
393 typedef const coap_bin_const_t *(*coap_dtls_id_callback_t)(
394  struct coap_bin_const_t *identity,
395  coap_session_t *coap_session,
396  void *arg);
411 typedef const coap_dtls_spsk_info_t *(*coap_dtls_psk_sni_callback_t)(
412  const char *sni,
413  coap_session_t *coap_session,
414  void *arg);
415 
416 #define COAP_DTLS_SPSK_SETUP_VERSION 1
421 typedef struct coap_dtls_spsk_t {
422  uint8_t version;
425  /* Options to enable different TLS functionality in libcoap */
426  uint8_t reserved[7];
428  /* Size of 7 chosen to align to next
429  * parameter, so if newly defined option
430  * it can use one of the reserverd slot so
431  * no need to change
432  * COAP_DTLS_SPSK_SETUP_VERSION and just
433  * decrement the reserved[] count.
434  */
435 
453 
454 
464 void coap_dtls_set_log_level(int level);
465 
472 int coap_dtls_get_log_level(void);
473 
474 
475 #endif /* COAP_DTLS_H */
Clock Handling.
coap_dtls_key_t *(* coap_dtls_pki_sni_callback_t)(const char *sni, void *arg)
Server Name Indication (SNI) Validation callback that can be set up by coap_context_set_pki().
Definition: coap_dtls.h:231
struct coap_dtls_cpsk_info_t coap_dtls_cpsk_info_t
The structure that holds the Client PSK information.
struct coap_dtls_key_t coap_dtls_key_t
The structure that holds the PKI key information.
struct coap_dtls_spsk_t coap_dtls_spsk_t
The structure used for defining the Server PSK setup data to be used.
struct coap_dtls_cpsk_t coap_dtls_cpsk_t
The structure used for defining the Client PSK setup data to be used.
struct coap_pki_key_pkcs11_t coap_pki_key_pkcs11_t
The structure that holds the PKI PKCS11 definitions.
const coap_dtls_spsk_info_t *(* coap_dtls_psk_sni_callback_t)(const char *sni, coap_session_t *coap_session, void *arg)
PSK SNI callback that can be set up by coap_context_set_psk2().
Definition: coap_dtls.h:411
coap_dtls_role_t
Definition: coap_dtls.h:27
int coap_tls_is_supported(void)
Check whether TLS is available.
Definition: coap_notls.c:20
struct coap_tls_version_t coap_tls_version_t
The structure used for returning the underlying (D)TLS library information.
struct coap_pki_key_pem_t coap_pki_key_pem_t
The structure that holds the PKI PEM definitions.
const coap_bin_const_t *(* coap_dtls_id_callback_t)(struct coap_bin_const_t *identity, coap_session_t *coap_session, void *arg)
Identity Validation callback that can be set up by coap_context_set_psk2().
Definition: coap_dtls.h:393
const coap_dtls_cpsk_info_t *(* coap_dtls_ih_callback_t)(struct coap_str_const_t *hint, coap_session_t *coap_session, void *arg)
Identity Hint Validation callback that can be set up by coap_new_client_session_psk2().
Definition: coap_dtls.h:324
coap_pki_key_t
The enum used for determining the PKI key formats.
Definition: coap_dtls.h:144
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:25
struct coap_dtls_spsk_info_t coap_dtls_spsk_info_t
The structure that holds the Server Pre-Shared Key and Identity Hint information.
int coap_dtls_is_supported(void)
Check whether DTLS is available.
Definition: coap_notls.c:15
struct coap_pki_key_asn1_t coap_pki_key_asn1_t
The structure that holds the PKI ASN.1 (DER) definitions.
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:88
struct coap_pki_key_pem_buf_t coap_pki_key_pem_buf_t
The structure that holds the PKI PEM buffer definitions.
coap_asn1_privatekey_type_t
The enum used for determining the provided PKI ASN.1 (DER) Private Key formats.
Definition: coap_dtls.h:123
coap_tls_library_t
Definition: coap_dtls.h:48
struct coap_dtls_pki_t coap_dtls_pki_t
The structure used for defining the PKI setup data to be used.
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 int depth, int validated, void *arg)
CN Validation callback that can be set up by coap_context_set_pki().
Definition: coap_dtls.h:111
@ COAP_DTLS_ROLE_SERVER
Internal function invoked for server.
Definition: coap_dtls.h:29
@ COAP_DTLS_ROLE_CLIENT
Internal function invoked for client.
Definition: coap_dtls.h:28
@ COAP_PKI_KEY_PKCS11
The PKI key type is PKCS11 (DER)
Definition: coap_dtls.h:148
@ COAP_PKI_KEY_PEM_BUF
The PKI key type is PEM buffer.
Definition: coap_dtls.h:147
@ COAP_PKI_KEY_PEM
The PKI key type is PEM file.
Definition: coap_dtls.h:145
@ COAP_PKI_KEY_ASN1
The PKI key type is ASN.1 (DER) buffer.
Definition: coap_dtls.h:146
@ COAP_ASN1_PKEY_DH
DH type.
Definition: coap_dtls.h:132
@ COAP_ASN1_PKEY_NONE
NONE.
Definition: coap_dtls.h:124
@ COAP_ASN1_PKEY_TLS1_PRF
TLS1_PRF type.
Definition: coap_dtls.h:137
@ COAP_ASN1_PKEY_RSA2
RSA2 type.
Definition: coap_dtls.h:126
@ COAP_ASN1_PKEY_DSA
DSA type.
Definition: coap_dtls.h:127
@ COAP_ASN1_PKEY_DHX
DHX type.
Definition: coap_dtls.h:133
@ COAP_ASN1_PKEY_DSA4
DSA4 type.
Definition: coap_dtls.h:131
@ COAP_ASN1_PKEY_DSA2
DSA2 type.
Definition: coap_dtls.h:129
@ COAP_ASN1_PKEY_RSA
RSA type.
Definition: coap_dtls.h:125
@ COAP_ASN1_PKEY_DSA1
DSA1 type.
Definition: coap_dtls.h:128
@ COAP_ASN1_PKEY_HKDF
HKDF type.
Definition: coap_dtls.h:138
@ COAP_ASN1_PKEY_EC
EC type.
Definition: coap_dtls.h:134
@ COAP_ASN1_PKEY_DSA3
DSA3 type.
Definition: coap_dtls.h:130
@ COAP_ASN1_PKEY_HMAC
HMAC type.
Definition: coap_dtls.h:135
@ COAP_ASN1_PKEY_CMAC
CMAC type.
Definition: coap_dtls.h:136
@ COAP_TLS_LIBRARY_GNUTLS
Using GnuTLS library.
Definition: coap_dtls.h:52
@ COAP_TLS_LIBRARY_TINYDTLS
Using TinyDTLS library.
Definition: coap_dtls.h:50
@ COAP_TLS_LIBRARY_NOTLS
No DTLS library.
Definition: coap_dtls.h:49
@ COAP_TLS_LIBRARY_OPENSSL
Using OpenSSL library.
Definition: coap_dtls.h:51
@ COAP_TLS_LIBRARY_MBEDTLS
Using Mbed TLS library.
Definition: coap_dtls.h:53
void coap_dtls_set_log_level(int level)
Sets the (D)TLS logging level to the specified level.
Definition: coap_notls.c:85
int coap_dtls_get_log_level(void)
Get the current (D)TLS logging.
Definition: coap_notls.c:90
CoAP binary data definition with const data.
Definition: str.h:56
The structure that holds the Client PSK information.
Definition: coap_dtls.h:303
coap_bin_const_t key
Definition: coap_dtls.h:305
coap_bin_const_t identity
Definition: coap_dtls.h:304
The structure used for defining the Client PSK setup data to be used.
Definition: coap_dtls.h:334
uint8_t version
Definition: coap_dtls.h:335
void * ih_call_back_arg
Passed in to the Identity Hint callback function.
Definition: coap_dtls.h:355
char * client_sni
If not NULL, SNI to use in client TLS setup.
Definition: coap_dtls.h:358
coap_dtls_ih_callback_t validate_ih_call_back
Identity Hint check callback function.
Definition: coap_dtls.h:354
coap_dtls_cpsk_info_t psk_info
Client PSK definition.
Definition: coap_dtls.h:363
uint8_t reserved[7]
Set to COAP_DTLS_CPSK_SETUP_VERSION to support this version of the struct.
Definition: coap_dtls.h:339
The structure that holds the PKI key information.
Definition: coap_dtls.h:208
coap_pki_key_pem_t pem
for PEM file keys
Definition: coap_dtls.h:211
coap_pki_key_pkcs11_t pkcs11
for PKCS11 keys
Definition: coap_dtls.h:214
union coap_dtls_key_t::@2 key
coap_pki_key_pem_buf_t pem_buf
for PEM memory keys
Definition: coap_dtls.h:212
coap_pki_key_t key_type
key format type
Definition: coap_dtls.h:209
coap_pki_key_asn1_t asn1
for ASN.1 (DER) memory keys
Definition: coap_dtls.h:213
The structure used for defining the PKI setup data to be used.
Definition: coap_dtls.h:240
uint8_t allow_no_crl
1 ignore if CRL not there
Definition: coap_dtls.h:254
void * cn_call_back_arg
Passed in to the CN callback function.
Definition: coap_dtls.h:276
uint8_t allow_short_rsa_length
1 if small RSA keysizes are allowed
Definition: coap_dtls.h:257
uint8_t cert_chain_validation
1 if to check cert_chain_verify_depth
Definition: coap_dtls.h:251
uint8_t allow_bad_md_hash
1 if unsupported MD hashes are allowed
Definition: coap_dtls.h:256
uint8_t version
Definition: coap_dtls.h:241
uint8_t check_cert_revocation
1 if revocation checks wanted
Definition: coap_dtls.h:253
coap_dtls_pki_sni_callback_t validate_sni_call_back
SNI check callback function.
Definition: coap_dtls.h:283
uint8_t cert_chain_verify_depth
recommended depth is 3
Definition: coap_dtls.h:252
uint8_t reserved[3]
Reserved - must be set to 0 for future compatibility.
Definition: coap_dtls.h:261
coap_dtls_security_setup_t additional_tls_setup_call_back
Additional Security callback handler that is invoked when libcoap has done the standard,...
Definition: coap_dtls.h:291
uint8_t allow_expired_certs
1 if expired certs are allowed
Definition: coap_dtls.h:250
uint8_t verify_peer_cert
Set to COAP_DTLS_PKI_SETUP_VERSION to support this version of the struct.
Definition: coap_dtls.h:245
char * client_sni
If not NULL, SNI to use in client TLS setup.
Definition: coap_dtls.h:293
uint8_t allow_self_signed
1 if self-signed certs are allowed.
Definition: coap_dtls.h:248
void * sni_call_back_arg
Passed in to the sni callback function.
Definition: coap_dtls.h:284
coap_dtls_cn_callback_t validate_cn_call_back
CN check callback function.
Definition: coap_dtls.h:275
uint8_t allow_expired_crl
1 if expired crl is allowed
Definition: coap_dtls.h:255
uint8_t is_rpk_not_cert
1 is RPK instead of Public Certificate.
Definition: coap_dtls.h:258
uint8_t check_common_ca
1 if peer cert is to be signed by the same CA as the local cert
Definition: coap_dtls.h:246
coap_dtls_key_t pki_key
PKI key definition.
Definition: coap_dtls.h:297
The structure that holds the Server Pre-Shared Key and Identity Hint information.
Definition: coap_dtls.h:370
coap_bin_const_t hint
Definition: coap_dtls.h:371
coap_bin_const_t key
Definition: coap_dtls.h:372
The structure used for defining the Server PSK setup data to be used.
Definition: coap_dtls.h:421
coap_dtls_psk_sni_callback_t validate_sni_call_back
SNI check callback function.
Definition: coap_dtls.h:448
coap_dtls_id_callback_t validate_id_call_back
Identity check callback function.
Definition: coap_dtls.h:440
uint8_t version
Definition: coap_dtls.h:422
uint8_t reserved[7]
Set to COAP_DTLS_SPSK_SETUP_VERSION to support this version of the struct.
Definition: coap_dtls.h:426
void * id_call_back_arg
Passed in to the Identity callback function.
Definition: coap_dtls.h:441
void * sni_call_back_arg
Passed in to the SNI callback function.
Definition: coap_dtls.h:449
coap_dtls_spsk_info_t psk_info
Server PSK definition.
Definition: coap_dtls.h:451
The structure that holds the PKI ASN.1 (DER) definitions.
Definition: coap_dtls.h:183
const uint8_t * private_key
ASN1 (DER) Private Key.
Definition: coap_dtls.h:186
coap_asn1_privatekey_type_t private_key_type
Private Key Type.
Definition: coap_dtls.h:190
size_t public_cert_len
ASN1 Public Cert length.
Definition: coap_dtls.h:188
size_t private_key_len
ASN1 Private Key length.
Definition: coap_dtls.h:189
const uint8_t * ca_cert
ASN1 (DER) Common CA Cert.
Definition: coap_dtls.h:184
size_t ca_cert_len
ASN1 CA Cert length.
Definition: coap_dtls.h:187
const uint8_t * public_cert
ASN1 (DER) Public Cert, or Public Key if RPK.
Definition: coap_dtls.h:185
The structure that holds the PKI PEM buffer definitions.
Definition: coap_dtls.h:169
size_t ca_cert_len
PEM buffer CA Cert length.
Definition: coap_dtls.h:175
const uint8_t * ca_cert
PEM buffer Common CA Cert.
Definition: coap_dtls.h:170
size_t private_key_len
PEM buffer Private Key length.
Definition: coap_dtls.h:177
const uint8_t * private_key
PEM buffer Private Key If RPK and 'EC PRIVATE KEY' this can be used for both the public_cert and priv...
Definition: coap_dtls.h:172
size_t public_cert_len
PEM buffer Public Cert length.
Definition: coap_dtls.h:176
const uint8_t * public_cert
PEM buffer Public Cert, or Public Key if RPK.
Definition: coap_dtls.h:171
The structure that holds the PKI PEM definitions.
Definition: coap_dtls.h:154
const char * ca_file
File location of Common CA in PEM format.
Definition: coap_dtls.h:155
const char * public_cert
File location of Public Cert.
Definition: coap_dtls.h:156
const char * private_key
File location of Private Key in PEM format.
Definition: coap_dtls.h:157
The structure that holds the PKI PKCS11 definitions.
Definition: coap_dtls.h:196
const char * private_key
pkcs11: URI for Private Key
Definition: coap_dtls.h:199
const char * ca
pkcs11: URI for Common CA Certificate
Definition: coap_dtls.h:197
const char * user_pin
User pin to access PKCS11.
Definition: coap_dtls.h:200
const char * public_cert
pkcs11: URI for Public Cert
Definition: coap_dtls.h:198
Abstraction of virtual session that can be attached to coap_context_t (client) or coap_endpoint_t (se...
CoAP string data definition with const data.
Definition: str.h:38
The structure used for returning the underlying (D)TLS library information.
Definition: coap_dtls.h:60
uint64_t built_version
(D)TLS Built against Library Version
Definition: coap_dtls.h:63
coap_tls_library_t type
Library type.
Definition: coap_dtls.h:62
uint64_t version
(D)TLS runtime Library Version
Definition: coap_dtls.h:61