1 /*
2  * SPDX-FileCopyrightText: 2017-2024 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 
8 #ifndef _ESP_CRT_BUNDLE_H_
9 #define _ESP_CRT_BUNDLE_H_
10 
11 #include "esp_err.h"
12 #include "mbedtls/ssl.h"
13 
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17 
18 
19 /**
20  * @brief      Attach and enable use of a bundle for certificate verification
21  *
22  * Attach and enable use of a bundle for certificate verification through a verification callback.
23  * If no specific bundle has been set through esp_crt_bundle_set() it will default to the
24  * bundle defined in menuconfig and embedded in the binary.
25  *
26  * @param[in]  conf      The config struct for the SSL connection.
27  *
28  * @return
29  *             - ESP_OK  if adding certificates was successful.
30  *             - Other   if an error occurred or an action must be taken by the calling process.
31  */
32 esp_err_t esp_crt_bundle_attach(void *conf);
33 
34 
35 /**
36  * @brief      Disable and dealloc the certification bundle
37  *
38  * Removes the certificate verification callback and deallocates used resources
39  *
40  * @param[in]  conf      The config struct for the SSL connection.
41  */
42 void esp_crt_bundle_detach(mbedtls_ssl_config *conf);
43 
44 
45 /**
46  * @brief      Set the default certificate bundle used for verification
47  *
48  * Overrides the default certificate bundle only in case of successful initialization. In most use cases the bundle should be
49  * set through menuconfig. The bundle needs to be sorted by subject name since binary search is
50  * used to find certificates.
51  *
52  * @param[in]  x509_bundle     A pointer to the certificate bundle.
53  *
54  * @param[in]  bundle_size     Size of the certificate bundle in bytes.
55  *
56  * @return
57  *             - ESP_OK  if adding certificates was successful.
58  *             - Other   if an error occurred or an action must be taken by the calling process.
59  */
60 esp_err_t esp_crt_bundle_set(const uint8_t *x509_bundle, size_t bundle_size);
61 
62 /**
63  * @brief   Check if the given CA certificate chain is the default "dummy"
64  *          certificate chain attached by the esp_crt_bundle
65  *
66  * @param ca_chain  A pointer to the CA chain.
67  * @return true     if the ca_chain is the dummy CA chain attached by esp_crt_bundle
68  * @return false    otherwise
69  */
70 bool esp_crt_bundle_in_use(const mbedtls_x509_crt* ca_chain);
71 
72 #ifdef __cplusplus
73 }
74 #endif
75 
76 #endif //_ESP_CRT_BUNDLE_H_
77