Flash encryption: Support enabling flash encryption in bootloader, app support

* App access functions are all flash encryption-aware
* Documentation for flash encryption
* Partition read/write is flash aware
* New encrypted write function

components/bootloader_support/include/esp_efuse.h

@@ -0,0 +1,56 @@
+// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+#ifndef _ESP_EFUSE_H
+#define _ESP_EFUSE_H
+
+#include "soc/efuse_reg.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* @brief Permanently update values written to the efuse write registers
+ *
+ * After updating EFUSE_BLKx_WDATAx_REG registers with new values to
+ * write, call this function to permanently write them to efuse.
+ *
+ * @note Setting bits in efuse is permanent, they cannot be unset.
+ *
+ * @note Due to this restriction you don't need to copy values to
+ * Efuse write registers from the matching read registers, bits which
+ * are set in the read register but unset in the matching write
+ * register will be unchanged when new values are burned.
+ *
+ * @note This function is not threadsafe, if calling code updates
+ * efuse values from multiple tasks then this is caller's
+ * responsibility to serialise.
+ *
+ * After burning new efuses, the read registers are updated to match
+ * the new efuse values.
+ */
+void esp_efuse_burn_new_values(void);
+
+/* @brief Reset efuse write registers
+ *
+ * Efuse write registers are written to zero, to negate
+ * any changes that have been staged here.
+ */
+void esp_efuse_reset(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __ESP_EFUSE_H */
+

components/bootloader_support/include/esp_flash_encrypt.h

@@ -0,0 +1,91 @@
+// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+#ifndef __ESP32_FLASH_ENCRYPT_H
+#define __ESP32_FLASH_ENCRYPT_H
+
+#include <stdbool.h>
+#include <esp_err.h>
+#include "esp_spi_flash.h"
+#include "soc/efuse_reg.h"
+
+/* Support functions for flash encryption features.
+
+   Can be compiled as part of app or bootloader code.
+*/
+
+/** @brief Is flash encryption currently enabled in hardware?
+ *
+ * Flash encryption is enabled if the FLASH_CRYPT_CNT efuse has an odd number of bits set.
+ *
+ * @return true if flash encryption is enabled.
+ */
+static inline bool esp_flash_encryption_enabled(void) {
+    uint32_t flash_crypt_cnt = REG_GET_FIELD(EFUSE_BLK0_RDATA0_REG, EFUSE_RD_FLASH_CRYPT_CNT);
+    return __builtin_parity(flash_crypt_cnt) == 1;
+}
+
+/* @brief Update on-device flash encryption
+ *
+ * Intended to be called as part of the bootloader process if flash
+ * encryption is enabled in device menuconfig.
+ *
+ * If FLASH_CRYPT_CNT efuse parity is 1 (ie odd number of bits set),
+ * then return ESP_OK immediately (indicating flash encryption is enabled
+ * and functional).
+ *
+ * If FLASH_CRYPT_CNT efuse parity is 0 (ie even number of bits set),
+ * assume the flash has just been written with plaintext that needs encrypting.
+ *
+ * The following regions of flash are encrypted in place:
+ *
+ * - The bootloader image, if a valid plaintext image is found.[*]
+ * - The partition table, if a valid plaintext table is found.
+ * - Any app partition that contains a valid plaintext app image.
+ * - Any other partitions with the "encrypt" flag set. [**]
+ *
+ * After the re-encryption process completes, a '1' bit is added to the
+ * FLASH_CRYPT_CNT value (setting the parity to 1) and the EFUSE is re-burned.
+ *
+ * [*] If reflashing bootloader with secure boot enabled, pre-encrypt
+ * the bootloader before writing it to flash or secure boot will fail.
+ *
+ * [**] For this reason, if serial re-flashing a previous flashed
+ * device with secure boot enabled and using FLASH_CRYPT_CNT to
+ * trigger re-encryption, you must simultaneously re-flash plaintext
+ * content to all partitions with the "encrypt" flag set or this
+ * data will be corrupted (encrypted twice).
+ *
+ * @note The post-condition of this function is that all
+ * partitions that should be encrypted are encrypted.
+ *
+ * @note Take care not to power off the device while this function
+ * is running, or the partition currently being encrypted will be lost.
+ *
+ * @return ESP_OK if all operations succeeded, ESP_ERR_INVALID_STATE
+ * if a fatal error occured during encryption of all partitions.
+ */
+esp_err_t esp_flash_encrypt_check_and_update(void);
+
+
+/** @brief Encrypt-in-place a block of flash sectors
+ *
+ * @param src_addr Source offset in flash. Should be multiple of 4096 bytes.
+ * @param data_length Length of data to encrypt in bytes. Will be rounded up to next multiple of 4096 bytes.
+ *
+ * @return ESP_OK if all operations succeeded, ESP_ERR_FLASH_OP_FAIL
+ * if SPI flash fails, ESP_ERR_FLASH_OP_TIMEOUT if flash times out.
+ */
+esp_err_t esp_flash_encrypt_region(uint32_t src_addr, size_t data_length);
+
+#endif

components/bootloader_support/include/esp_flash_partitions.h

@@ -0,0 +1,39 @@
+// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+#ifndef __ESP_FLASH_PARTITIONS_H
+#define __ESP_FLASH_PARTITIONS_H
+
+#include "esp_err.h"
+#include "esp_flash_data_types.h"
+#include <stdbool.h>
+
+/* Pre-partition table fixed flash offsets */
+#define ESP_BOOTLOADER_DIGEST_OFFSET 0x0
+#define ESP_BOOTLOADER_OFFSET 0x1000 /* Offset of bootloader image. Has matching value in bootloader KConfig.projbuild file. */
+#define ESP_PARTITION_TABLE_OFFSET 0x8000 /* Offset of partition table. Has matching value in partition_table Kconfig.projbuild file. */
+
+#define ESP_PARTITION_TABLE_MAX_LEN 0xC00 /* Maximum length of partition table data */
+#define ESP_PARTITION_TABLE_MAX_ENTRIES (ESP_PARTITION_TABLE_MAX_LEN / sizeof(esp_partition_info_t)) /* Maximum length of partition table data, including terminating entry */
+
+/* @brief Verify the partition table (does not include verifying secure boot cryptographic signature)
+ *
+ * @param partition_table Pointer to at least ESP_PARTITION_TABLE_MAX_ENTRIES of potential partition table data. (ESP_PARTITION_TABLE_MAX_LEN bytes.)
+ * @param log_errors Log errors if the partition table is invalid.
+ * @param num_partitions If result is ESP_OK, num_partitions is updated with total number of partitions (not including terminating entry).
+ *
+ * @return ESP_OK on success, ESP_ERR_INVALID_STATE if partition table is not valid.
+ */
+esp_err_t esp_partition_table_basic_verify(const esp_partition_info_t *partition_table, bool log_errors, int *num_partitions);
+
+#endif

components/bootloader_support/include/esp_image_format.h

@@ -77,33 +77,40 @@ typedef struct {
 /**
  * @brief Read an ESP image header from flash.
  *
+ * If encryption is enabled, data will be transparently decrypted.
+ *
  * @param src_addr Address in flash to load image header. Must be 4 byte aligned.
+ * @param log_errors Log error output if image header appears invalid.
  * @param[out] image_header Pointer to an esp_image_header_t struture to be filled with data. If the function fails, contents are undefined.
  *
  * @return ESP_OK if image header was loaded, ESP_ERR_IMAGE_FLASH_FAIL
  * if a SPI flash error occurs, ESP_ERR_IMAGE_INVALID if the image header
  * appears invalid.
  */
-esp_err_t esp_image_load_header(uint32_t src_addr, esp_image_header_t *image_header);
+esp_err_t esp_image_load_header(uint32_t src_addr, bool log_errors, esp_image_header_t *image_header);
 
 /**
  * @brief Read the segment header and data offset of a segment in the image.
  *
+ * If encryption is enabled, data will be transparently decrypted.
+ *
  * @param index Index of the segment to load information for.
  * @param src_addr Base address in flash of the image.
  * @param[in] image_header Pointer to the flash image header, already loaded by @ref esp_image_load_header().
+ * @param log_errors Log errors reading the segment header.
  * @param[out] segment_header Pointer to a segment header structure to be filled with data. If the function fails, contents are undefined.
  * @param[out] segment_data_offset Pointer to the data offset of the segment.
  *
  * @return ESP_OK if segment_header & segment_data_offset were loaded successfully, ESP_ERR_IMAGE_FLASH_FAIL if a SPI flash error occurs, ESP_ERR_IMAGE_INVALID if the image header appears invalid, ESP_ERR_INVALID_ARG if the index is invalid.
  */
-esp_err_t esp_image_load_segment_header(uint8_t index, uint32_t src_addr, const esp_image_header_t *image_header, esp_image_segment_header_t *segment_header, uint32_t *segment_data_offset);
+esp_err_t esp_image_load_segment_header(uint8_t index, uint32_t src_addr, const esp_image_header_t *image_header, bool log_errors, esp_image_segment_header_t *segment_header, uint32_t *segment_data_offset);
 
 
 /**
- * @brief Return length of an image in flash. Non-cryptographically validates image integrity in the process.
+ * @brief Non-cryptographically validate app image integrity. On success, length of image is provided to caller.
  *
- * If the image has a secure boot signature appended, the signature is not checked and this length is not included in the result.
+ * If the image has a secure boot signature appended, the signature is not checked and this length is not included in the
+ * output value.
  *
  * Image validation checks:
  * - Magic byte
@@ -111,13 +118,17 @@ esp_err_t esp_image_load_segment_header(uint8_t index, uint32_t src_addr, const
  * - Total image no longer than 16MB
  * - 8 bit image checksum is valid
  *
+ * If flash encryption is enabled, the image will be tranpsarently decrypted.
+ *
  * @param src_addr Offset of the start of the image in flash. Must be 4 byte aligned.
+ * @param allow_decrypt If true and flash encryption is enabled, the image will be transparently decrypted.
+ * @param log_errors Log errors verifying the image.
  * @param[out] length Length of the image, set to a value if the image is valid. Can be null.
  *
  * @return ESP_OK if image is valid, ESP_FAIL or ESP_ERR_IMAGE_INVALID on errors.
  *
  */
-esp_err_t esp_image_basic_verify(uint32_t src_addr, uint32_t *length);
+esp_err_t esp_image_basic_verify(uint32_t src_addr, bool log_errors, uint32_t *length);
 
 
 typedef struct {

components/bootloader_support/include/esp_secure_boot.h

@@ -67,9 +67,25 @@ esp_err_t esp_secure_boot_permanently_enable(void);
  * @param src_addr Starting offset of the data in flash.
  * @param length Length of data in bytes. Signature is appended -after- length bytes.
  *
+ * If flash encryption is enabled, the image will be transparently decrypted while being verified.
+ *
  * @return ESP_OK if signature is valid, ESP_ERR_INVALID_STATE if
  * signature fails, ESP_FAIL for other failures (ie can't read flash).
  */
 esp_err_t esp_secure_boot_verify_signature(uint32_t src_addr, uint32_t length);
 
+/** @brief Secure boot verification block, on-flash data format. */
+typedef struct {
+    uint32_t version;
+    uint8_t signature[64];
+} esp_secure_boot_sig_block_t;
+
+#define FLASH_OFFS_SECURE_BOOT_IV_DIGEST 0
+
+/** @brief Secure boot IV+digest header */
+typedef struct {
+    uint8_t iv[128];
+    uint8_t digest[64];
+} esp_secure_boot_iv_digest_t;
+
 #endif