1 /* 2 * SPDX-FileCopyrightText: 2015-2022 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_attr.h" 10 #include "esp_err.h" 11 #include "soc/soc_caps.h" 12 #ifndef BOOTLOADER_BUILD 13 #include "spi_flash_mmap.h" 14 #endif 15 #include "hal/efuse_ll.h" 16 #include "sdkconfig.h" 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 /* @brief Flash encryption mode based on efuse values 23 */ 24 typedef enum { 25 ESP_FLASH_ENC_MODE_DISABLED, // flash encryption is not enabled (flash crypt cnt=0) 26 ESP_FLASH_ENC_MODE_DEVELOPMENT, // flash encryption is enabled but for Development (reflash over UART allowed) 27 ESP_FLASH_ENC_MODE_RELEASE // flash encryption is enabled for Release (reflash over UART disabled) 28 } esp_flash_enc_mode_t; 29 30 /** 31 * @file esp_partition.h 32 * @brief Support functions for flash encryption features 33 * 34 * Can be compiled as part of app or bootloader code. 35 */ 36 37 /** @brief Is flash encryption currently enabled in hardware? 38 * 39 * Flash encryption is enabled if the FLASH_CRYPT_CNT efuse has an odd number of bits set. 40 * 41 * @return true if flash encryption is enabled. 42 */ 43 bool esp_flash_encryption_enabled(void); 44 45 /* @brief Update on-device flash encryption 46 * 47 * Intended to be called as part of the bootloader process if flash 48 * encryption is enabled in device menuconfig. 49 * 50 * If FLASH_CRYPT_CNT efuse parity is 1 (ie odd number of bits set), 51 * then return ESP_OK immediately (indicating flash encryption is enabled 52 * and functional). 53 * 54 * If FLASH_CRYPT_CNT efuse parity is 0 (ie even number of bits set), 55 * assume the flash has just been written with plaintext that needs encrypting. 56 * 57 * The following regions of flash are encrypted in place: 58 * 59 * - The bootloader image, if a valid plaintext image is found.[*] 60 * - The partition table, if a valid plaintext table is found. 61 * - Any app partition that contains a valid plaintext app image. 62 * - Any other partitions with the "encrypt" flag set. [**] 63 * 64 * After the re-encryption process completes, a '1' bit is added to the 65 * FLASH_CRYPT_CNT value (setting the parity to 1) and the EFUSE is re-burned. 66 * 67 * [*] If reflashing bootloader with secure boot enabled, pre-encrypt 68 * the bootloader before writing it to flash or secure boot will fail. 69 * 70 * [**] For this reason, if serial re-flashing a previous flashed 71 * device with secure boot enabled and using FLASH_CRYPT_CNT to 72 * trigger re-encryption, you must simultaneously re-flash plaintext 73 * content to all partitions with the "encrypt" flag set or this 74 * data will be corrupted (encrypted twice). 75 * 76 * @note The post-condition of this function is that all 77 * partitions that should be encrypted are encrypted. 78 * 79 * @note Take care not to power off the device while this function 80 * is running, or the partition currently being encrypted will be lost. 81 * 82 * @note RTC_WDT will reset while encryption operations will be performed (if RTC_WDT is configured). 83 * 84 * @return ESP_OK if all operations succeeded, ESP_ERR_INVALID_STATE 85 * if a fatal error occured during encryption of all partitions. 86 */ 87 esp_err_t esp_flash_encrypt_check_and_update(void); 88 89 /** @brief Returns the Flash Encryption state and prints it 90 * 91 * @return True - Flash Encryption is enabled 92 * False - Flash Encryption is not enabled 93 */ 94 bool esp_flash_encrypt_state(void); 95 96 /** @brief Checks if the first initialization was done 97 * 98 * If the first initialization was done then FLASH_CRYPT_CNT != 0 99 * 100 * @return true - the first initialization was done 101 * false - the first initialization was NOT done 102 */ 103 bool esp_flash_encrypt_initialized_once(void); 104 105 /** @brief The first initialization of Flash Encryption key and related eFuses 106 * 107 * @return ESP_OK if all operations succeeded 108 */ 109 esp_err_t esp_flash_encrypt_init(void); 110 111 /** @brief Encrypts flash content 112 * 113 * @return ESP_OK if all operations succeeded 114 */ 115 esp_err_t esp_flash_encrypt_contents(void); 116 117 /** @brief Activates Flash encryption on the chip 118 * 119 * It burns FLASH_CRYPT_CNT eFuse based on the CONFIG_SECURE_FLASH_ENCRYPTION_MODE_RELEASE option. 120 * 121 * @return ESP_OK if all operations succeeded 122 */ 123 esp_err_t esp_flash_encrypt_enable(void); 124 125 /** @brief Returns True if the write protection of FLASH_CRYPT_CNT is set 126 * 127 * @param print_error Print error if it is write protected 128 * 129 * @return true - if FLASH_CRYPT_CNT is write protected 130 */ 131 bool esp_flash_encrypt_is_write_protected(bool print_error); 132 133 /** @brief Encrypt-in-place a block of flash sectors 134 * 135 * @note This function resets RTC_WDT between operations with sectors. 136 * @param src_addr Source offset in flash. Should be multiple of 4096 bytes. 137 * @param data_length Length of data to encrypt in bytes. Will be rounded up to next multiple of 4096 bytes. 138 * 139 * @return ESP_OK if all operations succeeded, ESP_ERR_FLASH_OP_FAIL 140 * if SPI flash fails, ESP_ERR_FLASH_OP_TIMEOUT if flash times out. 141 */ 142 esp_err_t esp_flash_encrypt_region(uint32_t src_addr, size_t data_length); 143 144 /** @brief Write protect FLASH_CRYPT_CNT 145 * 146 * Intended to be called as a part of boot process if flash encryption 147 * is enabled but secure boot is not used. This should protect against 148 * serial re-flashing of an unauthorised code in absence of secure boot. 149 * 150 * @note On ESP32 V3 only, write protecting FLASH_CRYPT_CNT will also prevent 151 * disabling UART Download Mode. If both are wanted, call 152 * esp_efuse_disable_rom_download_mode() before calling this function. 153 * 154 */ 155 void esp_flash_write_protect_crypt_cnt(void); 156 157 /** @brief Return the flash encryption mode 158 * 159 * The API is called during boot process but can also be called by 160 * application to check the current flash encryption mode of ESP32 161 * 162 * @return 163 */ 164 esp_flash_enc_mode_t esp_get_flash_encryption_mode(void); 165 166 167 /** @brief Check the flash encryption mode during startup 168 * 169 * @note This function is called automatically during app startup, 170 * it doesn't need to be called from the app. 171 * 172 * Verifies the flash encryption config during startup: 173 * 174 * - Correct any insecure flash encryption settings if hardware 175 * Secure Boot is enabled. 176 * - Log warnings if the efuse config doesn't match the project 177 * config in any way 178 */ 179 void esp_flash_encryption_init_checks(void); 180 181 /** @brief Set all secure eFuse features related to flash encryption 182 * 183 * @return 184 * - ESP_OK - Successfully 185 */ 186 esp_err_t esp_flash_encryption_enable_secure_features(void); 187 188 /** @brief Returns the verification status for all physical security features of flash encryption in release mode 189 * 190 * If the device has flash encryption feature configured in the release mode, 191 * then it is highly recommended to call this API in the application startup code. 192 * This API verifies the sanity of the eFuse configuration against 193 * the release (production) mode of the flash encryption feature. 194 * 195 * @return 196 * - True - all eFuses are configured correctly 197 * - False - not all eFuses are configured correctly. 198 */ 199 bool esp_flash_encryption_cfg_verify_release_mode(void); 200 201 /** @brief Switches Flash Encryption from "Development" to "Release" 202 * 203 * If already in "Release" mode, the function will do nothing. 204 * If flash encryption efuse is not enabled yet then abort. 205 * It burns: 206 * - "disable encrypt in dl mode" 207 * - set FLASH_CRYPT_CNT efuse to max 208 */ 209 void esp_flash_encryption_set_release_mode(void); 210 211 #ifdef __cplusplus 212 } 213 #endif 214
