1 /*
2 * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6 #pragma once
7
8 #include <stdbool.h>
9 #include <esp_err.h>
10 #include "soc/efuse_periph.h"
11 #include "esp_image_format.h"
12 #include "esp_rom_efuse.h"
13 #include "sdkconfig.h"
14 #include "esp_rom_crc.h"
15
16 #if CONFIG_IDF_TARGET_ESP32
17 #include "esp32/rom/efuse.h"
18 #include "esp32/rom/secure_boot.h"
19 #elif CONFIG_IDF_TARGET_ESP32S2
20 #include "esp32s2/rom/efuse.h"
21 #include "esp32s2/rom/secure_boot.h"
22 #elif CONFIG_IDF_TARGET_ESP32C3
23 #include "esp32c3/rom/efuse.h"
24 #include "esp32c3/rom/secure_boot.h"
25 #elif CONFIG_IDF_TARGET_ESP32S3
26 #include "esp32s3/rom/efuse.h"
27 #include "esp32s3/rom/secure_boot.h"
28 #elif CONFIG_IDF_TARGET_ESP32H2
29 #include "esp32h2/rom/efuse.h"
30 #include "esp32h2/rom/secure_boot.h"
31 #endif
32
33 #ifdef CONFIG_SECURE_BOOT_V1_ENABLED
34 #if !defined(CONFIG_SECURE_SIGNED_ON_BOOT) || !defined(CONFIG_SECURE_SIGNED_ON_UPDATE) || !defined(CONFIG_SECURE_SIGNED_APPS)
35 #error "internal sdkconfig error, secure boot should always enable all signature options"
36 #endif
37 #endif
38
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42
43 /* Support functions for secure boot features.
44
45 Can be compiled as part of app or bootloader code.
46 */
47
48 #define ESP_SECURE_BOOT_DIGEST_LEN 32
49
50 #ifdef CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH
51 #include "esp_efuse.h"
52 #include "esp_efuse_table.h"
53 #endif
54
55 /** @brief Is secure boot currently enabled in hardware?
56 *
57 * This means that the ROM bootloader code will only boot
58 * a verified secure bootloader from now on.
59 *
60 * @return true if secure boot is enabled.
61 */
esp_secure_boot_enabled(void)62 static inline bool esp_secure_boot_enabled(void)
63 {
64 #if CONFIG_IDF_TARGET_ESP32
65 #ifdef CONFIG_SECURE_BOOT_V1_ENABLED
66 #ifndef CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH
67 return REG_READ(EFUSE_BLK0_RDATA6_REG) & EFUSE_RD_ABS_DONE_0;
68 #else
69 return esp_efuse_read_field_bit(ESP_EFUSE_ABS_DONE_0);
70 #endif
71 #elif CONFIG_SECURE_BOOT_V2_ENABLED
72 #ifndef CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH
73 return ets_use_secure_boot_v2();
74 #else
75 return esp_efuse_read_field_bit(ESP_EFUSE_ABS_DONE_1);
76 #endif
77 #endif
78 #else
79 #ifndef CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH
80 return esp_rom_efuse_is_secure_boot_enabled();
81 #else
82 return esp_efuse_read_field_bit(ESP_EFUSE_SECURE_BOOT_EN);
83 #endif
84 #endif
85 return false; /* Secure Boot not enabled in menuconfig */
86 }
87
88 /** @brief Generate secure digest from bootloader image
89 *
90 * @important This function is intended to be called from bootloader code only.
91 *
92 * This function is only used in the context of the Secure Boot V1 scheme.
93 *
94 * If secure boot is not yet enabled for bootloader, this will:
95 * 1) generate the secure boot key and burn it on EFUSE
96 * (without enabling R/W protection)
97 * 2) generate the digest from bootloader and save it
98 * to flash address 0x0
99 *
100 * If first boot gets interrupted after calling this function
101 * but before esp_secure_boot_permanently_enable() is called, then
102 * the key burned on EFUSE will not be regenerated, unless manually
103 * done using espefuse.py tool
104 *
105 * @return ESP_OK if secure boot digest is generated
106 * successfully or found to be already present
107 */
108 esp_err_t esp_secure_boot_generate_digest(void);
109
110 /** @brief Enable secure boot V1 if it is not already enabled.
111 *
112 * @important If this function succeeds, secure boot V1 is permanently
113 * enabled on the chip via efuse.
114 *
115 * @important This function is intended to be called from bootloader code only.
116 *
117 * @important In case of Secure Boot V1, this will enable r/w protection
118 * of secure boot key on EFUSE, therefore it is to be ensured that
119 * esp_secure_boot_generate_digest() is called before this .If secure boot is not
120 * yet enabled for bootloader, this will
121 * 1) enable R/W protection of secure boot key on EFUSE
122 * 2) enable secure boot by blowing the EFUSE_RD_ABS_DONE_0 efuse.
123 *
124 * This function does not verify secure boot of the bootloader (the
125 * ROM bootloader does this.)
126 *
127 * Will fail if efuses have been part-burned in a way that indicates
128 * secure boot should not or could not be correctly enabled.
129 *
130 * @return ESP_ERR_INVALID_STATE if efuse state doesn't allow
131 * secure boot to be enabled cleanly. ESP_OK if secure boot
132 * is enabled on this chip from now on.
133 */
134 esp_err_t esp_secure_boot_permanently_enable(void);
135
136 /** @brief Enables secure boot V2 if it is not already enabled.
137 *
138 * @important If this function succeeds, secure boot V2 is permanently
139 * enabled on the chip via efuse.
140 *
141 * @important This function is intended to be called from bootloader code only.
142 *
143 * @important In case of Secure Boot V2, this will enable write protection
144 * of secure boot key on EFUSE in BLK2. .If secure boot is not
145 * yet enabled for bootloader, this will
146 * 1) enable W protection of secure boot key on EFUSE
147 * 2) enable secure boot by blowing the EFUSE_RD_ABS_DONE_1 efuse.
148 *
149 * This function does not verify secure boot of the bootloader (the
150 * ROM bootloader does this.)
151 *
152 * @param image_data Image metadata of the application to be loaded.
153 *
154 * Will fail if efuses have been part-burned in a way that indicates
155 * secure boot should not or could not be correctly enabled.
156 *
157 * @return ESP_ERR_INVALID_STATE if efuse state doesn't allow
158 * secure boot to be enabled cleanly. ESP_OK if secure boot
159 * is enabled on this chip from now on.
160 */
161 esp_err_t esp_secure_boot_v2_permanently_enable(const esp_image_metadata_t *image_data);
162
163 /** @brief Verify the secure boot signature appended to some binary data in flash.
164 *
165 * For ECDSA Scheme (Secure Boot V1) - deterministic ECDSA w/ SHA256 image
166 * For RSA Scheme (Secure Boot V2) - RSA-PSS Verification of the SHA-256 image
167 *
168 * Public key is compiled into the calling program in the ECDSA Scheme.
169 * See the apt docs/security/secure-boot-v1.rst or docs/security/secure-boot-v2.rst for details.
170 *
171 * @param src_addr Starting offset of the data in flash.
172 * @param length Length of data in bytes. Signature is appended -after- length bytes.
173 *
174 * If flash encryption is enabled, the image will be transparently decrypted while being verified.
175 *
176 * @note This function doesn't have any fault injection resistance so should not be called
177 * during a secure boot itself (but can be called when verifying an update, etc.)
178 *
179 * @return ESP_OK if signature is valid, ESP_ERR_INVALID_STATE if
180 * signature fails, ESP_FAIL for other failures (ie can't read flash).
181 */
182 esp_err_t esp_secure_boot_verify_signature(uint32_t src_addr, uint32_t length);
183
184 /** @brief Secure boot verification block, on-flash data format. */
185 typedef struct {
186 uint32_t version;
187 uint8_t signature[64];
188 } esp_secure_boot_sig_block_t;
189
190 /** @brief Verify the ECDSA secure boot signature block for Secure Boot V1.
191 *
192 * Calculates Deterministic ECDSA w/ SHA256 based on the SHA256 hash of the image. ECDSA signature
193 * verification must be enabled in project configuration to use this function.
194 *
195 * Similar to esp_secure_boot_verify_signature(), but can be used when the digest is precalculated.
196 * @param sig_block Pointer to ECDSA signature block data
197 * @param image_digest Pointer to 32 byte buffer holding SHA-256 hash.
198 * @param verified_digest Pointer to 32 byte buffer that will receive verified digest if verification completes. (Used during bootloader implementation only, result is invalid otherwise.)
199 *
200 */
201 esp_err_t esp_secure_boot_verify_ecdsa_signature_block(const esp_secure_boot_sig_block_t *sig_block, const uint8_t *image_digest, uint8_t *verified_digest);
202
203 #if !CONFIG_IDF_TARGET_ESP32 || CONFIG_ESP32_REV_MIN_3
204 /**
205 * @brief Structure to hold public key digests calculated from the signature blocks of a single image.
206 *
207 * Each image can have one or more signature blocks (up to SECURE_BOOT_NUM_BLOCKS). Each signature block includes a public key.
208 */
209 typedef struct {
210 uint8_t key_digests[SECURE_BOOT_NUM_BLOCKS][ESP_SECURE_BOOT_DIGEST_LEN]; /* SHA of the public key components in the signature block */
211 unsigned num_digests; /* Number of valid digests, starting at index 0 */
212 } esp_image_sig_public_key_digests_t;
213
214 /** @brief Verify the RSA secure boot signature block for Secure Boot V2.
215 *
216 * Performs RSA-PSS Verification of the SHA-256 image based on the public key
217 * in the signature block, compared against the public key digest stored in efuse.
218 *
219 * Similar to esp_secure_boot_verify_signature(), but can be used when the digest is precalculated.
220 * @param sig_block Pointer to RSA signature block data
221 * @param image_digest Pointer to 32 byte buffer holding SHA-256 hash.
222 * @param verified_digest Pointer to 32 byte buffer that will receive verified digest if verification completes. (Used during bootloader implementation only, result is invalid otherwise.)
223 *
224 */
225 esp_err_t esp_secure_boot_verify_rsa_signature_block(const ets_secure_boot_signature_t *sig_block, const uint8_t *image_digest, uint8_t *verified_digest);
226 #endif // !CONFIG_IDF_TARGET_ESP32 || CONFIG_ESP32_REV_MIN_3
227
228 /** @brief Legacy ECDSA verification function
229 *
230 * @note Deprecated, call either esp_secure_boot_verify_ecdsa_signature_block() or esp_secure_boot_verify_rsa_signature_block() instead.
231 *
232 * @param sig_block Pointer to ECDSA signature block data
233 * @param image_digest Pointer to 32 byte buffer holding SHA-256 hash.
234 */
235 esp_err_t esp_secure_boot_verify_signature_block(const esp_secure_boot_sig_block_t *sig_block, const uint8_t *image_digest)
236 __attribute__((deprecated("use esp_secure_boot_verify_ecdsa_signature_block instead")));
237
238
239 #define FLASH_OFFS_SECURE_BOOT_IV_DIGEST 0
240
241 /** @brief Secure boot IV+digest header */
242 typedef struct {
243 uint8_t iv[128];
244 uint8_t digest[64];
245 } esp_secure_boot_iv_digest_t;
246
247 /** @brief Check the secure boot V2 during startup
248 *
249 * @note This function is called automatically during app startup,
250 * it doesn't need to be called from the app.
251 *
252 * Verifies the secure boot config during startup:
253 *
254 * - Correct any insecure secure boot settings
255 */
256 void esp_secure_boot_init_checks(void);
257
258 #if !BOOTLOADER_BUILD && CONFIG_SECURE_SIGNED_APPS_RSA_SCHEME
259
260 /** @brief Scan the current running app for signature blocks
261 *
262 * @note This function doesn't verify that the signatures are valid or the
263 * corresponding public keys are trusted, it only reads the number of signature
264 * blocks present and optionally calculates the digests of the public keys
265 * provided in the signature blocks.
266 *
267 * @param digest_public_keys If true, the key_digests fields in the
268 * public_key_digests structure will be filled with the digests of the public
269 * key provided in each signature block. Note that if Secure Boot V2 is enabled,
270 * each public key will only be trusted if the same digest is also present in
271 * eFuse (but this is not checked by this function).
272 *
273 * @param public_key_digests[out] Structure is initialized with the num_digests
274 * field set to the number of signatures found. If digest_public_keys is set,
275 * the public key digests are also calculated and stored here.
276 *
277 * @return
278 * - ESP_OK - At least one signature was found
279 * - ESP_ERR_NOT_FOUND - No signatures were found, num_digests value will be zero
280 * - ESP_FAIL - An error occured trying to read the signature blocks from flash
281 */
282 esp_err_t esp_secure_boot_get_signature_blocks_for_running_app(bool digest_public_keys, esp_image_sig_public_key_digests_t *public_key_digests);
283
284 #endif // !BOOTLOADER_BUILD && CONFIG_SECURE_SIGNED_APPS_RSA_SCHEME
285
286 /** @brief Set all secure eFuse features related to secure_boot
287 *
288 * @return
289 * - ESP_OK - Successfully
290 */
291 esp_err_t esp_secure_boot_enable_secure_features(void);
292
293 #ifdef __cplusplus
294 }
295 #endif
296
