libcoap 4.3.4
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 * SPDX-License-Identifier: BSD-2-Clause
8 *
9 * This file is part of the CoAP library libcoap. Please see README for terms
10 * of use.
11 */
12
18#ifndef COAP_DTLS_H_
19#define COAP_DTLS_H_
20
21#include "coap_time.h"
22#include "coap_str.h"
23
32
33#ifndef COAP_DTLS_HINT_LENGTH
34#define COAP_DTLS_HINT_LENGTH 128
35#endif
36#ifndef COAP_DTLS_MAX_PSK_IDENTITY
37#define COAP_DTLS_MAX_PSK_IDENTITY 64
38#endif
39#ifndef COAP_DTLS_MAX_PSK
40#define COAP_DTLS_MAX_PSK 64
41#endif
42
43typedef enum coap_dtls_role_t {
47
48#define COAP_DTLS_RPK_CERT_CN "RPK"
49
56
62int coap_tls_is_supported(void);
63
70
77
84
91
92typedef enum coap_tls_library_t {
99
104typedef struct coap_tls_version_t {
105 uint64_t version;
107 uint64_t built_version;
109
116
132typedef int (*coap_dtls_security_setup_t)(void *tls_session,
133 coap_dtls_pki_t *setup_data);
134
155typedef int (*coap_dtls_cn_callback_t)(const char *cn,
156 const uint8_t *asn1_public_cert,
157 size_t asn1_length,
158 coap_session_t *coap_session,
159 unsigned int depth,
160 int validated,
161 void *arg);
162
184
188typedef enum coap_pki_key_t {
194
198typedef struct coap_pki_key_pem_t {
199 const char *ca_file;
200 const char *public_cert;
201 const char *private_key;
203
214 const uint8_t *ca_cert;
215 const uint8_t *public_cert;
216 const uint8_t *private_key;
219 size_t ca_cert_len;
223
227typedef struct coap_pki_key_asn1_t {
228 const uint8_t *ca_cert;
229 const uint8_t *public_cert;
230 const uint8_t *private_key;
231 size_t ca_cert_len;
236
240typedef struct coap_pki_key_pkcs11_t {
241 const char *ca;
242 const char *public_cert;
243 const char *private_key;
244 const char *user_pin;
248
252typedef struct coap_dtls_key_t {
254 union {
261
275typedef coap_dtls_key_t *(*coap_dtls_pki_sni_callback_t)(const char *sni,
276 void *arg);
277
278
279#define COAP_DTLS_PKI_SETUP_VERSION 1
285 uint8_t version;
288 /* Options to enable different TLS functionality in libcoap */
298 uint8_t allow_no_crl;
305 uint8_t reserved[3];
307 /* Size of 3 chosen to align to next
308 * parameter, so if newly defined option
309 * it can use one of the reserved slots so
310 * no need to change
311 * COAP_DTLS_PKI_SETUP_VERSION and just
312 * decrement the reserved[] count.
313 */
314
336
342};
343
347typedef struct coap_dtls_cpsk_info_t {
351
368typedef const coap_dtls_cpsk_info_t *(*coap_dtls_ih_callback_t)(
369 coap_str_const_t *hint,
370 coap_session_t *coap_session,
371 void *arg);
372
373#define COAP_DTLS_CPSK_SETUP_VERSION 1
378typedef struct coap_dtls_cpsk_t {
379 uint8_t version;
382 /* Options to enable different TLS functionality in libcoap */
383 uint8_t reserved[7];
385 /* Size of 7 chosen to align to next
386 * parameter, so if newly defined option
387 * it can use one of the reserverd slot so
388 * no need to change
389 * COAP_DTLS_CPSK_SETUP_VERSION and just
390 * decrement the reserved[] count.
391 */
392
409
414typedef struct coap_dtls_spsk_info_t {
418
419
437typedef const coap_bin_const_t *(*coap_dtls_id_callback_t)(
438 coap_bin_const_t *identity,
439 coap_session_t *coap_session,
440 void *arg);
455typedef const coap_dtls_spsk_info_t *(*coap_dtls_psk_sni_callback_t)(
456 const char *sni,
457 coap_session_t *coap_session,
458 void *arg);
459
460#define COAP_DTLS_SPSK_SETUP_VERSION 1
465typedef struct coap_dtls_spsk_t {
466 uint8_t version;
469 /* Options to enable different TLS functionality in libcoap */
470 uint8_t reserved[7];
472 /* Size of 7 chosen to align to next
473 * parameter, so if newly defined option
474 * it can use one of the reserverd slot so
475 * no need to change
476 * COAP_DTLS_SPSK_SETUP_VERSION and just
477 * decrement the reserved[] count.
478 */
479
497
498
501#endif /* COAP_DTLS_H */
Strings to be used in the CoAP library.
Clock Handling.
const coap_bin_const_t *(* coap_dtls_id_callback_t)(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:437
struct coap_dtls_cpsk_info_t coap_dtls_cpsk_info_t
The structure that holds the Client PSK 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:69
int coap_dtls_psk_is_supported(void)
Check whether (D)TLS PSK is available.
Definition: coap_notls.c:37
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.
coap_dtls_role_t
Definition: coap_dtls.h:43
int coap_tls_is_supported(void)
Check whether TLS is available.
Definition: coap_notls.c:28
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.
coap_pki_key_t
The enum used for determining the PKI key formats.
Definition: coap_dtls.h:188
const coap_dtls_cpsk_info_t *(* coap_dtls_ih_callback_t)(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:368
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:23
struct coap_pki_key_asn1_t coap_pki_key_asn1_t
The structure that holds the PKI ASN.1 (DER) definitions.
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:167
int coap_dtls_pki_is_supported(void)
Check whether (D)TLS PKI is available.
Definition: coap_notls.c:46
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:455
int coap_dtls_rpk_is_supported(void)
Check whether (D)TLS RPK is available.
Definition: coap_notls.c:64
coap_tls_library_t
Definition: coap_dtls.h:92
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:155
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:275
int coap_dtls_pkcs11_is_supported(void)
Check whether (D)TLS PKCS11 is available.
Definition: coap_notls.c:55
int(* coap_dtls_security_setup_t)(void *tls_session, coap_dtls_pki_t *setup_data)
Additional Security setup handler that can be set up by coap_context_set_pki().
Definition: coap_dtls.h:132
@ COAP_DTLS_ROLE_SERVER
Internal function invoked for server.
Definition: coap_dtls.h:45
@ COAP_DTLS_ROLE_CLIENT
Internal function invoked for client.
Definition: coap_dtls.h:44
@ COAP_PKI_KEY_PKCS11
The PKI key type is PKCS11 (DER)
Definition: coap_dtls.h:192
@ COAP_PKI_KEY_PEM_BUF
The PKI key type is PEM buffer.
Definition: coap_dtls.h:191
@ COAP_PKI_KEY_PEM
The PKI key type is PEM file.
Definition: coap_dtls.h:189
@ COAP_PKI_KEY_ASN1
The PKI key type is ASN.1 (DER) buffer.
Definition: coap_dtls.h:190
@ COAP_ASN1_PKEY_DH
DH type.
Definition: coap_dtls.h:176
@ COAP_ASN1_PKEY_NONE
NONE.
Definition: coap_dtls.h:168
@ COAP_ASN1_PKEY_TLS1_PRF
TLS1_PRF type.
Definition: coap_dtls.h:181
@ COAP_ASN1_PKEY_RSA2
RSA2 type.
Definition: coap_dtls.h:170
@ COAP_ASN1_PKEY_DSA
DSA type.
Definition: coap_dtls.h:171
@ COAP_ASN1_PKEY_DHX
DHX type.
Definition: coap_dtls.h:177
@ COAP_ASN1_PKEY_DSA4
DSA4 type.
Definition: coap_dtls.h:175
@ COAP_ASN1_PKEY_DSA2
DSA2 type.
Definition: coap_dtls.h:173
@ COAP_ASN1_PKEY_RSA
RSA type.
Definition: coap_dtls.h:169
@ COAP_ASN1_PKEY_DSA1
DSA1 type.
Definition: coap_dtls.h:172
@ COAP_ASN1_PKEY_HKDF
HKDF type.
Definition: coap_dtls.h:182
@ COAP_ASN1_PKEY_EC
EC type.
Definition: coap_dtls.h:178
@ COAP_ASN1_PKEY_DSA3
DSA3 type.
Definition: coap_dtls.h:174
@ COAP_ASN1_PKEY_HMAC
HMAC type.
Definition: coap_dtls.h:179
@ COAP_ASN1_PKEY_CMAC
CMAC type.
Definition: coap_dtls.h:180
@ COAP_TLS_LIBRARY_GNUTLS
Using GnuTLS library.
Definition: coap_dtls.h:96
@ COAP_TLS_LIBRARY_TINYDTLS
Using TinyDTLS library.
Definition: coap_dtls.h:94
@ COAP_TLS_LIBRARY_NOTLS
No DTLS library.
Definition: coap_dtls.h:93
@ COAP_TLS_LIBRARY_OPENSSL
Using OpenSSL library.
Definition: coap_dtls.h:95
@ COAP_TLS_LIBRARY_MBEDTLS
Using Mbed TLS library.
Definition: coap_dtls.h:97
CoAP binary data definition with const data.
Definition: coap_str.h:64
The structure that holds the Client PSK information.
Definition: coap_dtls.h:347
coap_bin_const_t key
Definition: coap_dtls.h:349
coap_bin_const_t identity
Definition: coap_dtls.h:348
The structure used for defining the Client PSK setup data to be used.
Definition: coap_dtls.h:378
uint8_t version
Definition: coap_dtls.h:379
void * ih_call_back_arg
Passed in to the Identity Hint callback function.
Definition: coap_dtls.h:399
char * client_sni
If not NULL, SNI to use in client TLS setup.
Definition: coap_dtls.h:402
coap_dtls_ih_callback_t validate_ih_call_back
Identity Hint check callback function.
Definition: coap_dtls.h:398
coap_dtls_cpsk_info_t psk_info
Client PSK definition.
Definition: coap_dtls.h:407
uint8_t reserved[7]
Set to COAP_DTLS_CPSK_SETUP_VERSION to support this version of the struct.
Definition: coap_dtls.h:383
The structure that holds the PKI key information.
Definition: coap_dtls.h:252
coap_pki_key_pem_t pem
for PEM file keys
Definition: coap_dtls.h:255
coap_pki_key_pkcs11_t pkcs11
for PKCS11 keys
Definition: coap_dtls.h:258
union coap_dtls_key_t::@3 key
coap_pki_key_pem_buf_t pem_buf
for PEM memory keys
Definition: coap_dtls.h:256
coap_pki_key_t key_type
key format type
Definition: coap_dtls.h:253
coap_pki_key_asn1_t asn1
for ASN.1 (DER) memory keys
Definition: coap_dtls.h:257
The structure used for defining the PKI setup data to be used.
Definition: coap_dtls.h:284
uint8_t allow_no_crl
1 ignore if CRL not there
Definition: coap_dtls.h:298
void * cn_call_back_arg
Passed in to the CN callback function.
Definition: coap_dtls.h:320
uint8_t allow_short_rsa_length
1 if small RSA keysizes are allowed
Definition: coap_dtls.h:301
uint8_t cert_chain_validation
1 if to check cert_chain_verify_depth
Definition: coap_dtls.h:295
uint8_t allow_bad_md_hash
1 if unsupported MD hashes are allowed
Definition: coap_dtls.h:300
uint8_t version
Definition: coap_dtls.h:285
uint8_t check_cert_revocation
1 if revocation checks wanted
Definition: coap_dtls.h:297
coap_dtls_pki_sni_callback_t validate_sni_call_back
SNI check callback function.
Definition: coap_dtls.h:327
uint8_t cert_chain_verify_depth
recommended depth is 3
Definition: coap_dtls.h:296
uint8_t reserved[3]
Reserved - must be set to 0 for future compatibility.
Definition: coap_dtls.h:305
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:335
uint8_t allow_expired_certs
1 if expired certs are allowed
Definition: coap_dtls.h:294
uint8_t verify_peer_cert
Set to COAP_DTLS_PKI_SETUP_VERSION to support this version of the struct.
Definition: coap_dtls.h:289
char * client_sni
If not NULL, SNI to use in client TLS setup.
Definition: coap_dtls.h:337
uint8_t allow_self_signed
1 if self-signed certs are allowed.
Definition: coap_dtls.h:292
void * sni_call_back_arg
Passed in to the sni callback function.
Definition: coap_dtls.h:328
coap_dtls_cn_callback_t validate_cn_call_back
CN check callback function.
Definition: coap_dtls.h:319
uint8_t allow_expired_crl
1 if expired crl is allowed
Definition: coap_dtls.h:299
uint8_t is_rpk_not_cert
1 is RPK instead of Public Certificate.
Definition: coap_dtls.h:302
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:290
coap_dtls_key_t pki_key
PKI key definition.
Definition: coap_dtls.h:341
The structure that holds the Server Pre-Shared Key and Identity Hint information.
Definition: coap_dtls.h:414
coap_bin_const_t hint
Definition: coap_dtls.h:415
coap_bin_const_t key
Definition: coap_dtls.h:416
The structure used for defining the Server PSK setup data to be used.
Definition: coap_dtls.h:465
coap_dtls_psk_sni_callback_t validate_sni_call_back
SNI check callback function.
Definition: coap_dtls.h:492
coap_dtls_id_callback_t validate_id_call_back
Identity check callback function.
Definition: coap_dtls.h:484
uint8_t version
Definition: coap_dtls.h:466
uint8_t reserved[7]
Set to COAP_DTLS_SPSK_SETUP_VERSION to support this version of the struct.
Definition: coap_dtls.h:470
void * id_call_back_arg
Passed in to the Identity callback function.
Definition: coap_dtls.h:485
void * sni_call_back_arg
Passed in to the SNI callback function.
Definition: coap_dtls.h:493
coap_dtls_spsk_info_t psk_info
Server PSK definition.
Definition: coap_dtls.h:495
The structure that holds the PKI ASN.1 (DER) definitions.
Definition: coap_dtls.h:227
const uint8_t * private_key
ASN1 (DER) Private Key.
Definition: coap_dtls.h:230
coap_asn1_privatekey_type_t private_key_type
Private Key Type.
Definition: coap_dtls.h:234
size_t public_cert_len
ASN1 Public Cert length.
Definition: coap_dtls.h:232
size_t private_key_len
ASN1 Private Key length.
Definition: coap_dtls.h:233
const uint8_t * ca_cert
ASN1 (DER) Common CA Cert.
Definition: coap_dtls.h:228
size_t ca_cert_len
ASN1 CA Cert length.
Definition: coap_dtls.h:231
const uint8_t * public_cert
ASN1 (DER) Public Cert, or Public Key if RPK.
Definition: coap_dtls.h:229
The structure that holds the PKI PEM buffer definitions.
Definition: coap_dtls.h:213
size_t ca_cert_len
PEM buffer CA Cert length.
Definition: coap_dtls.h:219
const uint8_t * ca_cert
PEM buffer Common CA Cert.
Definition: coap_dtls.h:214
size_t private_key_len
PEM buffer Private Key length.
Definition: coap_dtls.h:221
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:216
size_t public_cert_len
PEM buffer Public Cert length.
Definition: coap_dtls.h:220
const uint8_t * public_cert
PEM buffer Public Cert, or Public Key if RPK.
Definition: coap_dtls.h:215
The structure that holds the PKI PEM definitions.
Definition: coap_dtls.h:198
const char * ca_file
File location of Common CA in PEM format.
Definition: coap_dtls.h:199
const char * public_cert
File location of Public Cert.
Definition: coap_dtls.h:200
const char * private_key
File location of Private Key in PEM format.
Definition: coap_dtls.h:201
The structure that holds the PKI PKCS11 definitions.
Definition: coap_dtls.h:240
const char * private_key
pkcs11: URI for Private Key
Definition: coap_dtls.h:243
const char * ca
pkcs11: URI for Common CA Certificate
Definition: coap_dtls.h:241
const char * user_pin
User pin to access PKCS11.
Definition: coap_dtls.h:244
const char * public_cert
pkcs11: URI for Public Cert
Definition: coap_dtls.h:242
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: coap_str.h:46
The structure used for returning the underlying (D)TLS library information.
Definition: coap_dtls.h:104
uint64_t built_version
(D)TLS Built against Library Version
Definition: coap_dtls.h:107
coap_tls_library_t type
Library type.
Definition: coap_dtls.h:106
uint64_t version
(D)TLS runtime Library Version
Definition: coap_dtls.h:105