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