From 4358f3b5737b5e53f01999d2bbbf5496dc59e1ee Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 24 Mar 2020 13:47:51 +1100 Subject: [PATCH] doc: Add warnings about using JTAG debugging with hardware security features This is related to the following issues but is not a fix, just documentation of a workaround until we can improve the support: https://github.com/espressif/esp-idf/issues/4878 https://github.com/espressif/esp-idf/issues/4734 --- .../jtag-debugging/tips-and-quirks.rst | 22 +++++++++++++++++-- docs/en/security/flash-encryption.rst | 10 +++++++-- docs/en/security/secure-boot-v1.rst | 9 ++++++++ docs/en/security/secure-boot-v2.rst | 10 +++++++++ .../jtag-debugging/tips-and-quirks.rst | 21 ++++++++++++++++++ 5 files changed, 68 insertions(+), 4 deletions(-) diff --git a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst index bb47fc1a5..784552581 100644 --- a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst @@ -259,8 +259,27 @@ Below is an excerpt from series of errors reported by GDB after the application cpu1: xtensa_resume (line 431): DSR (FFFFFFFF) indicates DIR instruction generated an exception! cpu1: xtensa_resume (line 431): DSR (FFFFFFFF) indicates DIR instruction generated an overrun! +.. _jtag-debugging-security-features: -.. _jtag-debugging-tip-at-firmware-issue: +JTAG with Flash Encryption or Secure Boot +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, enabling Flash Encryption and/or Secure Boot will disable JTAG debugging. On first boot, the bootloader will burn an eFuse bit to permanently disable JTAG at the same time it enables the other features. + +The project configuration option :ref:`CONFIG_SECURE_BOOT_ALLOW_JTAG` will keep JTAG enabled at this time, removing all physical security but allowing debugging. (Although the name suggests Secure Boot, this option can be applied even when only Flash Encryption is enabled). + +However, OpenOCD may attempt to automatically read and write the flash in order to set :ref:`software breakpoints `. This has two problems: + +- Software breakpoints are incompatible with Flash Encryption, OpenOCD currently has no support for encrypting or decrypting flash contents. +- If Secure Boot is enabled, setting a software breakpoint will change the digest of a signed app and make the signature invalid. This means if a software breakpoint is set and then a reset occurs, the signature verification will fail on boot. + +To disable software breakpoints while using JTAG, add an extra argument ``-c 'set ESP_FLASH_SIZE 0'`` to the start of the OpenOCD command line. For example:: + + openocd -c 'set ESP_FLASH_SIZE 0' -f board/esp32-wrover-kit-3.3v.cfg + +.. note:: + + For the same reason, the ESP-IDF app may fail bootloader verification of app signatures, when this option is enabled and a software breakpoint is set. .. only:: esp32 @@ -271,7 +290,6 @@ Below is an excerpt from series of errors reported by GDB after the application To make JTAG available, build new firmware that is not using pins GPIO12 to GPIO15 dedicated to JTAG communication. After that, flash the firmware onto your module. See also :ref:`jtag-debugging-tip-jtag-pins-reconfigured`. - .. _jtag-debugging-tip-reporting-issues: Reporting issues with OpenOCD / GDB diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index 72604c334..c7b471d4e 100644 --- a/docs/en/security/flash-encryption.rst +++ b/docs/en/security/flash-encryption.rst @@ -618,8 +618,8 @@ It is recommended to use flash encryption and secure boot together. However, if .. _flash-encryption-advanced-features: -Flash Encryption Advanced Features ----------------------------------- +Advanced Features +----------------- The following information is useful for advanced use of flash encryption: @@ -685,6 +685,12 @@ It is possible to write these eFuse manually, and write protect it before first It is strongly recommended to never write protect ``FLASH_CRYPT_CONFIG`` when it the value is zero. If this eFuse is set to zero, no bits in the flash encryption key are tweaked and the flash encryption algorithm is equivalent to AES ECB mode. +JTAG Debugging +^^^^^^^^^^^^^^ + +By default, when Flash Encryption is enabled (in either Development or Release mode) then JTAG debugging is disabled via eFuse. The bootloader does this on first boot, at the same time it enables flash encryption. + +See :ref:`jtag-debugging-security-features` for more information about using JTAG Debugging with Flash Encryption. Technical Details ----------------- diff --git a/docs/en/security/secure-boot-v1.rst b/docs/en/security/secure-boot-v1.rst index e583fe442..42dd95d94 100644 --- a/docs/en/security/secure-boot-v1.rst +++ b/docs/en/security/secure-boot-v1.rst @@ -315,3 +315,12 @@ How To Enable Signed App Verification 4. If you disable "Sign binaries during build" option then you'll have to enter path of a public key file used to verify signed images in "Secure boot public signature verification key". In this case, private signing key should be generated by following instructions in :ref:`secure-boot-generate-key`; public verification key and signed image should be generated by following instructions in :ref:`remote-sign-image`. +Advanced Features +----------------- + +JTAG Debugging +~~~~~~~~~~~~~~ + +By default, when Secure Boot is enabled then JTAG debugging is disabled via eFuse. The bootloader does this on first boot, at the same time it enables Secure Boot. + +See :ref:`jtag-debugging-security-features` for more information about using JTAG Debugging with either Secure Boot or signed app verification enabled. diff --git a/docs/en/security/secure-boot-v2.rst b/docs/en/security/secure-boot-v2.rst index d4e4ec0ef..c4d6d5036 100644 --- a/docs/en/security/secure-boot-v2.rst +++ b/docs/en/security/secure-boot-v2.rst @@ -253,3 +253,13 @@ Secure Boot & Flash Encryption ------------------------------ If secure boot is used without :doc:`Flash Encryption `, it is possible to launch "time-of-check to time-of-use" attack, where flash contents are swapped after the image is verified and running. Therefore, it is recommended to use both the features together. + +Advanced Features +----------------- + +JTAG Debugging +~~~~~~~~~~~~~~ + +By default, when Secure Boot is enabled then JTAG debugging is disabled via eFuse. The bootloader does this on first boot, at the same time it enables Secure Boot. + +See :ref:`jtag-debugging-security-features` for more information about using JTAG Debugging with either Secure Boot or signed app verification enabled. diff --git a/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst index 898bbd538..5aa66fc48 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst @@ -258,6 +258,27 @@ OpenOCD 需要知道当前使用的 JTAG 适配器的类型，以及其连接的 cpu1: xtensa_resume (line 431): DSR (FFFFFFFF) indicates DIR instruction generated an exception! cpu1: xtensa_resume (line 431): DSR (FFFFFFFF) indicates DIR instruction generated an overrun! +.. _jtag-debugging-security-features: + +JTAG with Flash Encryption or Secure Boot +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, enabling Flash Encryption and/or Secure Boot will disable JTAG debugging. On first boot, the bootloader will burn an eFuse bit to permanently disable JTAG at the same time it enables the other features. + +The project configuration option :ref:`CONFIG_SECURE_BOOT_ALLOW_JTAG` will keep JTAG enabled at this time, removing all physical security but allowing debugging. (Although the name suggests Secure Boot, this option can be applied even when only Flash Encryption is enabled). + +However, OpenOCD may attempt to automatically read and write the flash in order to set :ref:`software breakpoints `. This has two problems: + +- Software breakpoints are incompatible with Flash Encryption, OpenOCD currently has no support for encrypting or decrypting flash contents. +- If Secure Boot is enabled, setting a software breakpoint will change the digest of a signed app and make the signature invalid. This means if a software breakpoint is set and then a reset occurs, the signature verification will fail on boot. + +To disable software breakpoints while using JTAG, add an extra argument ``-c 'set ESP_FLASH_SIZE 0'`` to the start of the OpenOCD command line. For example:: + + openocd -c 'set ESP_FLASH_SIZE 0' -f board/esp32-wrover-kit-3.3v.cfg + +.. note:: + + For the same reason, the ESP-IDF app may fail bootloader verification of app signatures, when this option is enabled and a software breakpoint is set. .. _jtag-debugging-tip-reporting-issues: