libcoap 4.3.5rc1
Loading...
Searching...
No Matches
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 * Copyright (C) 2023-2024 Jon Shallow <supjps-libcoap@jpshallow.com>
7 *
8 * SPDX-License-Identifier: BSD-2-Clause
9 *
10 * This file is part of the CoAP library libcoap. Please see README for terms
11 * of use.
12 */
13
19#ifndef COAP_DTLS_H_
20#define COAP_DTLS_H_
21
22#include "coap_time.h"
23#include "coap_str.h"
24
33
34#ifndef COAP_DTLS_HINT_LENGTH
35#define COAP_DTLS_HINT_LENGTH 128
36#endif
37#ifndef COAP_DTLS_MAX_PSK_IDENTITY
38#define COAP_DTLS_MAX_PSK_IDENTITY 64
39#endif
40#ifndef COAP_DTLS_MAX_PSK
41#define COAP_DTLS_MAX_PSK 64
42#endif
43
48
49#define COAP_DTLS_RPK_CERT_CN "RPK"
50
57
63int coap_tls_is_supported(void);
64
71
78
85
92
102
110int coap_tls_engine_remove(void);
111
120
130
137
153typedef int (*coap_dtls_security_setup_t)(void *tls_session,
154 coap_dtls_pki_t *setup_data);
155
176typedef int (*coap_dtls_cn_callback_t)(const char *cn,
177 const uint8_t *asn1_public_cert,
178 size_t asn1_length,
179 coap_session_t *coap_session,
180 unsigned int depth,
181 int validated,
182 void *arg);
183
205
216
220typedef struct coap_pki_key_pem_t {
221 const char *ca_file;
223 const char *public_cert;
224 const char *private_key;
226
237 const uint8_t *ca_cert;
238 const uint8_t *public_cert;
239 const uint8_t *private_key;
242 size_t ca_cert_len;
246
259
263typedef struct coap_pki_key_pkcs11_t {
264 const char *ca;
265 const char *public_cert;
266 const char *private_key;
267 const char *user_pin;
271
297
317
331
345typedef coap_dtls_key_t *(*coap_dtls_pki_sni_callback_t)(const char *sni,
346 void *arg);
347
348
349#define COAP_DTLS_PKI_SETUP_VERSION 1
355 uint8_t version;
358 /* Options to enable different TLS functionality in libcoap */
368 uint8_t allow_no_crl;
375 uint8_t reserved[3];
377 /* Size of 3 chosen to align to next
378 * parameter, so if newly defined option
379 * it can use one of the reserved slots so
380 * no need to change
381 * COAP_DTLS_PKI_SETUP_VERSION and just
382 * decrement the reserved[] count.
383 */
384
406
412};
413
421
438typedef const coap_dtls_cpsk_info_t *(*coap_dtls_ih_callback_t)(
439 coap_str_const_t *hint,
440 coap_session_t *coap_session,
441 void *arg);
442
443#define COAP_DTLS_CPSK_SETUP_VERSION 1
448typedef struct coap_dtls_cpsk_t {
449 uint8_t version;
452 /* Options to enable different TLS functionality in libcoap */
453 uint8_t reserved[7];
455 /* Size of 7 chosen to align to next
456 * parameter, so if newly defined option
457 * it can use one of the reserverd slot so
458 * no need to change
459 * COAP_DTLS_CPSK_SETUP_VERSION and just
460 * decrement the reserved[] count.
461 */
462
479
488
489
507typedef const coap_bin_const_t *(*coap_dtls_id_callback_t)(
508 coap_bin_const_t *identity,
509 coap_session_t *coap_session,
510 void *arg);
525typedef const coap_dtls_spsk_info_t *(*coap_dtls_psk_sni_callback_t)(
526 const char *sni,
527 coap_session_t *coap_session,
528 void *arg);
529
530#define COAP_DTLS_SPSK_SETUP_VERSION 1
535typedef struct coap_dtls_spsk_t {
536 uint8_t version;
539 /* Options to enable different TLS functionality in libcoap */
540 uint8_t reserved[7];
542 /* Size of 7 chosen to align to next
543 * parameter, so if newly defined option
544 * it can use one of the reserverd slot so
545 * no need to change
546 * COAP_DTLS_SPSK_SETUP_VERSION and just
547 * decrement the reserved[] count.
548 */
549
567
570#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:507
struct coap_pki_key_define_t coap_pki_key_define_t
The structure that holds the PKI Definable key type definitions.
coap_pki_define_t
The enum to define the format of the key parameter definition.
Definition coap_dtls.h:275
int coap_tls_engine_configure(coap_str_const_t *conf_mem)
Configure an ENGINE for a TLS library.
Definition coap_notls.c:22
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:82
int coap_dtls_psk_is_supported(void)
Check whether (D)TLS PSK is available.
Definition coap_notls.c:50
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:44
int coap_tls_is_supported(void)
Check whether TLS is available.
Definition coap_notls.c:41
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.
int coap_tls_engine_remove(void)
Remove a previously configured ENGINE from a TLS library.
Definition coap_notls.c:28
coap_pki_key_t
The enum used for determining the PKI key formats.
Definition coap_dtls.h:209
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:438
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:36
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:188
int coap_dtls_pki_is_supported(void)
Check whether (D)TLS PKI is available.
Definition coap_notls.c:59
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:525
int coap_dtls_rpk_is_supported(void)
Check whether (D)TLS RPK is available.
Definition coap_notls.c:77
coap_tls_library_t
Definition coap_dtls.h:112
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:176
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:345
int coap_dtls_pkcs11_is_supported(void)
Check whether (D)TLS PKCS11 is available.
Definition coap_notls.c:68
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:153
@ COAP_PKI_KEY_DEF_PKCS11
The PKI key type is PKCS11 (pkcs11:...).
Definition coap_dtls.h:287
@ COAP_PKI_KEY_DEF_DER_BUF
The PKI key type is DER buffer (ASN.1).
Definition coap_dtls.h:284
@ COAP_PKI_KEY_DEF_PEM_BUF
The PKI key type is PEM buffer.
Definition coap_dtls.h:278
@ COAP_PKI_KEY_DEF_PEM
The PKI key type is PEM file.
Definition coap_dtls.h:276
@ COAP_PKI_KEY_DEF_ENGINE
The PKI key type is to be passed to ENGINE.
Definition coap_dtls.h:293
@ COAP_PKI_KEY_DEF_RPK_BUF
The PKI key type is RPK in buffer.
Definition coap_dtls.h:280
@ COAP_PKI_KEY_DEF_DER
The PKI key type is DER file.
Definition coap_dtls.h:282
@ COAP_PKI_KEY_DEF_PKCS11_RPK
The PKI key type is PKCS11 w/ RPK (pkcs11:...).
Definition coap_dtls.h:290
@ COAP_DTLS_ROLE_SERVER
Internal function invoked for server.
Definition coap_dtls.h:46
@ COAP_DTLS_ROLE_CLIENT
Internal function invoked for client.
Definition coap_dtls.h:45
@ COAP_PKI_KEY_PKCS11
The PKI key type is PKCS11 (DER)
Definition coap_dtls.h:213
@ COAP_PKI_KEY_PEM_BUF
The PKI key type is PEM buffer.
Definition coap_dtls.h:212
@ COAP_PKI_KEY_DEFINE
The individual PKI key types are Definable.
Definition coap_dtls.h:214
@ COAP_PKI_KEY_PEM
The PKI key type is PEM file.
Definition coap_dtls.h:210
@ COAP_PKI_KEY_ASN1
The PKI key type is ASN.1 (DER) buffer.
Definition coap_dtls.h:211
@ COAP_ASN1_PKEY_DH
DH type.
Definition coap_dtls.h:197
@ COAP_ASN1_PKEY_NONE
NONE.
Definition coap_dtls.h:189
@ COAP_ASN1_PKEY_TLS1_PRF
TLS1_PRF type.
Definition coap_dtls.h:202
@ COAP_ASN1_PKEY_RSA2
RSA2 type.
Definition coap_dtls.h:191
@ COAP_ASN1_PKEY_DSA
DSA type.
Definition coap_dtls.h:192
@ COAP_ASN1_PKEY_DHX
DHX type.
Definition coap_dtls.h:198
@ COAP_ASN1_PKEY_DSA4
DSA4 type.
Definition coap_dtls.h:196
@ COAP_ASN1_PKEY_DSA2
DSA2 type.
Definition coap_dtls.h:194
@ COAP_ASN1_PKEY_RSA
RSA type.
Definition coap_dtls.h:190
@ COAP_ASN1_PKEY_DSA1
DSA1 type.
Definition coap_dtls.h:193
@ COAP_ASN1_PKEY_HKDF
HKDF type.
Definition coap_dtls.h:203
@ COAP_ASN1_PKEY_EC
EC type.
Definition coap_dtls.h:199
@ COAP_ASN1_PKEY_DSA3
DSA3 type.
Definition coap_dtls.h:195
@ COAP_ASN1_PKEY_HMAC
HMAC type.
Definition coap_dtls.h:200
@ COAP_ASN1_PKEY_CMAC
CMAC type.
Definition coap_dtls.h:201
@ COAP_TLS_LIBRARY_WOLFSSL
Using wolfSSL library.
Definition coap_dtls.h:118
@ COAP_TLS_LIBRARY_GNUTLS
Using GnuTLS library.
Definition coap_dtls.h:116
@ COAP_TLS_LIBRARY_TINYDTLS
Using TinyDTLS library.
Definition coap_dtls.h:114
@ COAP_TLS_LIBRARY_NOTLS
No DTLS library.
Definition coap_dtls.h:113
@ COAP_TLS_LIBRARY_OPENSSL
Using OpenSSL library.
Definition coap_dtls.h:115
@ COAP_TLS_LIBRARY_MBEDTLS
Using Mbed TLS library.
Definition coap_dtls.h:117
CoAP binary data definition with const data.
Definition coap_str.h:64
The structure that holds the Client PSK information.
Definition coap_dtls.h:417
coap_bin_const_t key
Definition coap_dtls.h:419
coap_bin_const_t identity
Definition coap_dtls.h:418
The structure used for defining the Client PSK setup data to be used.
Definition coap_dtls.h:448
void * ih_call_back_arg
Passed in to the Identity Hint callback function.
Definition coap_dtls.h:469
char * client_sni
If not NULL, SNI to use in client TLS setup.
Definition coap_dtls.h:472
coap_dtls_ih_callback_t validate_ih_call_back
Identity Hint check callback function.
Definition coap_dtls.h:468
coap_dtls_cpsk_info_t psk_info
Client PSK definition.
Definition coap_dtls.h:477
uint8_t reserved[7]
Set to COAP_DTLS_CPSK_SETUP_VERSION to support this version of the struct.
Definition coap_dtls.h:453
The structure that holds the PKI key information.
Definition coap_dtls.h:321
coap_pki_key_define_t define
for definable type keys
Definition coap_dtls.h:328
coap_pki_key_pem_t pem
for PEM file keys
Definition coap_dtls.h:324
coap_pki_key_pkcs11_t pkcs11
for PKCS11 keys
Definition coap_dtls.h:327
union coap_dtls_key_t::@3 key
coap_pki_key_pem_buf_t pem_buf
for PEM memory keys
Definition coap_dtls.h:325
coap_pki_key_t key_type
key format type
Definition coap_dtls.h:322
coap_pki_key_asn1_t asn1
for ASN.1 (DER) memory keys
Definition coap_dtls.h:326
The structure used for defining the PKI setup data to be used.
Definition coap_dtls.h:354
uint8_t allow_no_crl
1 ignore if CRL not there
Definition coap_dtls.h:368
void * cn_call_back_arg
Passed in to the CN callback function.
Definition coap_dtls.h:390
uint8_t allow_short_rsa_length
1 if small RSA keysizes are allowed
Definition coap_dtls.h:371
uint8_t cert_chain_validation
1 if to check cert_chain_verify_depth
Definition coap_dtls.h:365
uint8_t allow_bad_md_hash
1 if unsupported MD hashes are allowed
Definition coap_dtls.h:370
uint8_t version
Definition coap_dtls.h:355
uint8_t check_cert_revocation
1 if revocation checks wanted
Definition coap_dtls.h:367
coap_dtls_pki_sni_callback_t validate_sni_call_back
SNI check callback function.
Definition coap_dtls.h:397
uint8_t cert_chain_verify_depth
recommended depth is 3
Definition coap_dtls.h:366
uint8_t reserved[3]
Reserved - must be set to 0 for future compatibility.
Definition coap_dtls.h:375
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:405
uint8_t allow_expired_certs
1 if expired certs are allowed
Definition coap_dtls.h:364
uint8_t verify_peer_cert
Set to COAP_DTLS_PKI_SETUP_VERSION to support this version of the struct.
Definition coap_dtls.h:359
char * client_sni
If not NULL, SNI to use in client TLS setup.
Definition coap_dtls.h:407
uint8_t allow_self_signed
1 if self-signed certs are allowed.
Definition coap_dtls.h:362
void * sni_call_back_arg
Passed in to the sni callback function.
Definition coap_dtls.h:398
coap_dtls_cn_callback_t validate_cn_call_back
CN check callback function.
Definition coap_dtls.h:389
uint8_t allow_expired_crl
1 if expired crl is allowed
Definition coap_dtls.h:369
uint8_t is_rpk_not_cert
1 is RPK instead of Public Certificate.
Definition coap_dtls.h:372
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:360
coap_dtls_key_t pki_key
PKI key definition.
Definition coap_dtls.h:411
The structure that holds the Server Pre-Shared Key and Identity Hint information.
Definition coap_dtls.h:484
coap_bin_const_t hint
Definition coap_dtls.h:485
coap_bin_const_t key
Definition coap_dtls.h:486
The structure used for defining the Server PSK setup data to be used.
Definition coap_dtls.h:535
coap_dtls_psk_sni_callback_t validate_sni_call_back
SNI check callback function.
Definition coap_dtls.h:562
coap_dtls_id_callback_t validate_id_call_back
Identity check callback function.
Definition coap_dtls.h:554
uint8_t reserved[7]
Set to COAP_DTLS_SPSK_SETUP_VERSION to support this version of the struct.
Definition coap_dtls.h:540
void * id_call_back_arg
Passed in to the Identity callback function.
Definition coap_dtls.h:555
void * sni_call_back_arg
Passed in to the SNI callback function.
Definition coap_dtls.h:563
coap_dtls_spsk_info_t psk_info
Server PSK definition.
Definition coap_dtls.h:565
The structure that holds the PKI ASN.1 (DER) definitions.
Definition coap_dtls.h:250
const uint8_t * private_key
ASN1 (DER) Private Key.
Definition coap_dtls.h:253
coap_asn1_privatekey_type_t private_key_type
Private Key Type.
Definition coap_dtls.h:257
size_t public_cert_len
ASN1 Public Cert length.
Definition coap_dtls.h:255
size_t private_key_len
ASN1 Private Key length.
Definition coap_dtls.h:256
const uint8_t * ca_cert
ASN1 (DER) Common CA Cert.
Definition coap_dtls.h:251
size_t ca_cert_len
ASN1 CA Cert length.
Definition coap_dtls.h:254
const uint8_t * public_cert
ASN1 (DER) Public Cert, or Public Key if RPK.
Definition coap_dtls.h:252
The structure that holds the PKI Definable key type definitions.
Definition coap_dtls.h:301
coap_const_char_ptr_t public_cert
define: Public Cert
Definition coap_dtls.h:303
coap_asn1_privatekey_type_t private_key_type
define: ASN1 Private Key Type (if needed)
Definition coap_dtls.h:311
const char * user_pin
define: User pin to access type PKCS11.
Definition coap_dtls.h:313
coap_const_char_ptr_t private_key
define: Private Key
Definition coap_dtls.h:304
coap_const_char_ptr_t ca
define: Common CA Certificate
Definition coap_dtls.h:302
size_t public_cert_len
define Public Cert length (if needed)
Definition coap_dtls.h:306
size_t ca_len
define CA Cert length (if needed)
Definition coap_dtls.h:305
coap_pki_define_t private_key_def
define: Private Key type definition
Definition coap_dtls.h:310
size_t private_key_len
define Private Key length (if needed)
Definition coap_dtls.h:307
coap_pki_define_t ca_def
define: Common CA type definition
Definition coap_dtls.h:308
coap_pki_define_t public_cert_def
define: Public Cert type definition
Definition coap_dtls.h:309
The structure that holds the PKI PEM buffer definitions.
Definition coap_dtls.h:236
size_t ca_cert_len
PEM buffer CA Cert length.
Definition coap_dtls.h:242
const uint8_t * ca_cert
PEM buffer Common CA Cert.
Definition coap_dtls.h:237
size_t private_key_len
PEM buffer Private Key length.
Definition coap_dtls.h:244
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:239
size_t public_cert_len
PEM buffer Public Cert length.
Definition coap_dtls.h:243
const uint8_t * public_cert
PEM buffer Public Cert, or Public Key if RPK.
Definition coap_dtls.h:238
The structure that holds the PKI PEM definitions.
Definition coap_dtls.h:220
const char * ca_file
File location of Common CA (and any intermediates) in PEM format.
Definition coap_dtls.h:221
const char * public_cert
File location of Public Cert.
Definition coap_dtls.h:223
const char * private_key
File location of Private Key in PEM format.
Definition coap_dtls.h:224
The structure that holds the PKI PKCS11 definitions.
Definition coap_dtls.h:263
const char * private_key
pkcs11: URI for Private Key
Definition coap_dtls.h:266
const char * ca
pkcs11: URI for Common CA Certificate
Definition coap_dtls.h:264
const char * user_pin
User pin to access PKCS11.
Definition coap_dtls.h:267
const char * public_cert
pkcs11: URI for Public Cert
Definition coap_dtls.h:265
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:125
uint64_t built_version
(D)TLS Built against Library Version
Definition coap_dtls.h:128
coap_tls_library_t type
Library type.
Definition coap_dtls.h:127
uint64_t version
(D)TLS runtime Library Version
Definition coap_dtls.h:126
CoAP union for handling signed / unsigned chars.
Definition coap_str.h:72