diff --git a/docs/docs_not_updated/esp32h4.txt b/docs/docs_not_updated/esp32h4.txt index d8624dfe3ed..33f0f0d10d9 100644 --- a/docs/docs_not_updated/esp32h4.txt +++ b/docs/docs_not_updated/esp32h4.txt @@ -108,7 +108,6 @@ api-reference/peripherals/temp_sensor.rst api-reference/peripherals/camera_driver.rst api-reference/peripherals/sdspi_share.rst api-reference/peripherals/ana_cmpr.rst -api-reference/peripherals/hmac.rst api-reference/peripherals/key_manager.rst api-reference/peripherals/sdspi_host.rst api-reference/peripherals/vad.rst @@ -116,14 +115,12 @@ api-reference/peripherals/i2s.rst api-reference/peripherals/sd_pullup_requirements.rst api-reference/peripherals/adc_calibration.rst api-reference/peripherals/lp_i2s.rst -api-reference/peripherals/ecdsa.rst api-reference/peripherals/spi_flash/index.rst api-reference/peripherals/spi_flash/spi_flash_concurrency.rst api-reference/peripherals/spi_flash/spi_flash_override_driver.rst api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst api-reference/peripherals/sdmmc_host.rst -api-reference/system/random.rst api-reference/system/mm_sync.rst api-reference/system/mm.rst api-reference/system/esp_https_ota.rst @@ -131,13 +128,6 @@ api-reference/system/sleep_modes.rst api-reference/system/ota.rst api-reference/system/inc/power_management_esp32h4.rst api-reference/system/power_management.rst -security/index.rst -security/flash-encryption.rst -security/secure-boot-v1.rst -security/security.rst -security/security-features-enablement-workflows.rst -security/secure-boot-v2.rst -security/vulnerabilities.rst security/tee/index.rst security/tee/tee-advanced.rst security/tee/tee-sec-storage.rst 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 050ad801ccf..ef487e6652e 100644 --- a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst @@ -253,7 +253,7 @@ By default, enabling Flash Encryption and/or Secure Boot will disable JTAG debug .. only:: SOC_HMAC_SUPPORTED - Please note that once JTAG is permanently disabled, it cannot be re-enabled for JTAG access. However, we do have the option of disabling JTAG softly. For more details on soft disabling and re-enabling soft-disabled JTAG, please refer to the :ref:`hmac_for_enabling_jtag`. + Please note that once JTAG is permanently disabled, it cannot be re-enabled for JTAG access. However, we do have the option of disabling JTAG softly. For more details on soft disabling and re-enabling soft-disabled JTAG, please refer to the :ref:`HMAC for Enabling JTAG `. 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). diff --git a/docs/en/api-reference/peripherals/hmac.rst b/docs/en/api-reference/peripherals/hmac.rst index cb79b78394c..6a9d9237b7f 100644 --- a/docs/en/api-reference/peripherals/hmac.rst +++ b/docs/en/api-reference/peripherals/hmac.rst @@ -34,35 +34,61 @@ On {IDF_TARGET_NAME}, the HMAC module works with a secret key burnt into the eFu This key can be made completely inaccessible for any resources outside the cryptographic modules, thus avoiding key leakage. -Furthermore, {IDF_TARGET_NAME} has three different application scenarios for its HMAC module: +.. only:: SOC_DIG_SIGN_SUPPORTED -#. HMAC is generated for software use -#. HMAC is used as a key for the RSA Digital Signature Peripheral (RSA_DS) -#. HMAC is used for enabling the soft-disabled JTAG interface + Furthermore, {IDF_TARGET_NAME} has three different application scenarios for its HMAC module: -The first mode is called **Upstream** mode, while the last two modes are called **Downstream** modes. + #. HMAC is generated for software use + #. HMAC is used as a key for the RSA Digital Signature Peripheral (RSA_DS) + #. HMAC is used for enabling the soft-disabled JTAG interface + + The first mode is called **Upstream** mode, while the last two modes are called **Downstream** modes. + +.. only:: not SOC_DIG_SIGN_SUPPORTED + + Furthermore, {IDF_TARGET_NAME} has two different application scenarios for its HMAC module: + + #. HMAC is generated for software use + #. HMAC is used for enabling the soft-disabled JTAG interface + + The first mode is called **Upstream** mode, while the second mode is called **Downstream** mode. eFuse Keys for HMAC ^^^^^^^^^^^^^^^^^^^ Six physical eFuse blocks can be used as keys for the HMAC module: block 4 ~ block 9. The enum :cpp:enum:`hmac_key_id_t` in the API maps them to ``HMAC_KEY0`` ~ ``HMAC_KEY5``. -Each key has a corresponding eFuse parameter **key purpose** determining for which of the three HMAC application scenarios (see below) the key may be used: +Each key has a corresponding eFuse parameter **key purpose** determining for which of the HMAC application scenarios (see below) the key may be used: -.. list-table:: - :widths: 15 70 - :header-rows: 1 +.. only:: SOC_DIG_SIGN_SUPPORTED - * - Key Purpose - - Application Scenario - * - 8 - - HMAC generated for software use - * - 7 - - HMAC used as a key for the RSA Digital Signature Peripheral (RSA_DS) - * - 6 - - HMAC used for enabling the soft-disabled JTAG interface - * - 5 - - HMAC both as a key for the RSA_DS module and for enabling JTAG + .. list-table:: + :widths: 15 70 + :header-rows: 1 + + * - Key Purpose + - Application Scenario + * - 8 + - HMAC generated for software use + * - 7 + - HMAC used as a key for the RSA Digital Signature Peripheral (RSA_DS) + * - 6 + - HMAC used for enabling the soft-disabled JTAG interface + * - 5 + - HMAC both as a key for the RSA_DS module and for enabling JTAG + +.. only:: not SOC_DIG_SIGN_SUPPORTED + + .. list-table:: + :widths: 15 70 + :header-rows: 1 + + * - Key Purpose + - Application Scenario + * - 8 + - HMAC generated for software use + * - 5, 6 + - HMAC used for enabling the soft-disabled JTAG interface (HMAC Downstream mode) This is to prevent the usage of a key for a different function than originally intended. @@ -79,16 +105,18 @@ In this case, the HMAC is given out to the software, e.g., to authenticate a mes The API to calculate the HMAC is :cpp:func:`psa_mac_compute`, which takes an opaque PSA key referencing an eFuse key block that contains the secret and has its purpose set to Upstream mode. -HMAC for RSA Digital Signature -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. only:: SOC_DIG_SIGN_SUPPORTED -Key purpose values: 7, 5 + HMAC for RSA Digital Signature + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The HMAC can be used as a key derivation function to decrypt private key parameters which are used by the RSA Digital Signature module. A standard message is used by the hardware in that case. You only need to provide the eFuse key block and purpose on the HMAC side, additional parameters are required for the RSA Digital Signature component in that case. + Key purpose values: 7, 5 -Neither the key nor the actual HMAC is ever exposed outside the HMAC module and RSA_DS component. The calculation of the HMAC and its handover to the RSA_DS component happen internally. + The HMAC can be used as a key derivation function to decrypt private key parameters which are used by the RSA Digital Signature module. A standard message is used by the hardware in that case. You only need to provide the eFuse key block and purpose on the HMAC side, additional parameters are required for the RSA Digital Signature component in that case. -For more details, see **{IDF_TARGET_NAME} Technical Reference Manual** > **RSA Digital Signature Peripheral (RSA_DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. + Neither the key nor the actual HMAC is ever exposed outside the HMAC module and RSA_DS component. The calculation of the HMAC and its handover to the RSA_DS component happen internally. + + For more details, see **{IDF_TARGET_NAME} Technical Reference Manual** > **RSA Digital Signature Peripheral (RSA_DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. .. _hmac_for_enabling_jtag: diff --git a/docs/en/api-reference/system/random.rst b/docs/en/api-reference/system/random.rst index a569be287bf..679946935b7 100644 --- a/docs/en/api-reference/system/random.rst +++ b/docs/en/api-reference/system/random.rst @@ -3,7 +3,7 @@ Random Number Generation :link_to_translation:`zh_CN:[中文]` -{IDF_TARGET_RF_NAME: default="Wi-Fi or Bluetooth", esp32s2="Wi-Fi", esp32h2="Bluetooth or 802.15.4 Thread/Zigbee", esp32c6="Wi-Fi or Bluetooth or 802.15.4 Thread/Zigbee", esp32c5="Wi-Fi or Bluetooth or 802.15.4 Thread/Zigbee"} +{IDF_TARGET_RF_NAME: default="Wi-Fi or Bluetooth", esp32s2="Wi-Fi", esp32h2="Bluetooth or 802.15.4 Thread/Zigbee", esp32h4="Bluetooth or 802.15.4 Thread/Zigbee", esp32c6="Wi-Fi or Bluetooth or 802.15.4 Thread/Zigbee", esp32c5="Wi-Fi or Bluetooth or 802.15.4 Thread/Zigbee"} {IDF_TARGET_RF_IS: default="are", esp32s2="is"} {IDF_TARGET_NAME} contains a hardware random number generator (RNG). You can use the APIs :cpp:func:`esp_random` and :cpp:func:`esp_fill_random` to obtained random values from it. diff --git a/docs/en/security/security-features-enablement-workflows.rst b/docs/en/security/security-features-enablement-workflows.rst index ab1c66bf21e..da00daad184 100644 --- a/docs/en/security/security-features-enablement-workflows.rst +++ b/docs/en/security/security-features-enablement-workflows.rst @@ -8,7 +8,7 @@ Security Features Enablement Workflows {IDF_TARGET_CRYPT_CNT:default="SPI_BOOT_CRYPT_CNT",esp32="FLASH_CRYPT_CNT"} {IDF_TARGET_CRYPT_CNT_MAX_VAL:default="7",esp32="127"} -{IDF_TARGET_SBV2_DEFAULT_SCHEME:default="RSA", esp32c2="ECDSA (V2)"} +{IDF_TARGET_SBV2_DEFAULT_SCHEME:default="RSA", esp32c2, esp32h4="ECDSA (V2)"} {IDF_TARGET_FLASH_ENC_ARGS:default="--aes-xts", esp32=""} Introduction diff --git a/docs/en/security/security.rst b/docs/en/security/security.rst index c6fb1ca255c..e2c370ddcec 100644 --- a/docs/en/security/security.rst +++ b/docs/en/security/security.rst @@ -190,7 +190,7 @@ JTAG - JTAG interface stays disabled if any of the security features are enabled. Please refer to :ref:`jtag-debugging-security-features` for more information. - JTAG interface can also be disabled in the absence of any other security features using :ref:`efuse_API`. - :SOC_HMAC_SUPPORTED: - {IDF_TARGET_NAME} supports soft disabling the JTAG interface and it can be re-enabled by programming a secret key through HMAC. (:ref:`hmac_for_enabling_jtag`) + :SOC_HMAC_SUPPORTED: - {IDF_TARGET_NAME} supports soft disabling the JTAG interface and it can be re-enabled by programming a secret key through HMAC. (:ref:`HMAC for Enabling JTAG `) UART Download Mode ^^^^^^^^^^^^^^^^^^ 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 1ec414a3c4d..5d40ffa05c1 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 @@ -253,7 +253,7 @@ JTAG 与 flash 加密和安全启动 .. only:: SOC_HMAC_SUPPORTED - 请注意，一旦 JTAG 被永久禁用，就无法重新启用以访问 JTAG。但是我们也提供了暂时禁用 (soft disable) JTAG 的选项。有关如何暂时禁用以及重新启用 JTAG，请参考 :ref:`hmac_for_enabling_jtag`。 + 请注意，一旦 JTAG 被永久禁用，就无法重新启用以访问 JTAG。但是我们也提供了暂时禁用 (soft disable) JTAG 的选项。有关如何暂时禁用以及重新启用 JTAG，请参考 :ref:`HMAC 启用 JTAG 接口 `。 Kconfig 配置项 :ref:`CONFIG_SECURE_BOOT_ALLOW_JTAG` 可以改变这个默认行为，使得用户即使开启了安全启动或者 flash 加密，仍会保留 JTAG 的功能。 diff --git a/docs/zh_CN/api-reference/peripherals/hmac.rst b/docs/zh_CN/api-reference/peripherals/hmac.rst index cd027012d70..24ad407a24a 100644 --- a/docs/zh_CN/api-reference/peripherals/hmac.rst +++ b/docs/zh_CN/api-reference/peripherals/hmac.rst @@ -34,13 +34,24 @@ 可将该密钥设置为禁止所有外部资源访问，避免密钥泄露。 -此外，在 {IDF_TARGET_NAME} 上的 HMAC 有以下三种应用场景： +.. only:: SOC_DIG_SIGN_SUPPORTED -#. HMAC 支持软件使用 -#. HMAC 用作 RSA 数字签名外设 (RSA_DS) 的密钥 -#. HMAC 用于启用软禁用的 JTAG 接口 + 此外，在 {IDF_TARGET_NAME} 上的 HMAC 有以下三种应用场景： -第一种应用场景称为 **上行** 模式，后两种应用场景称为 **下行** 模式。 + #. HMAC 支持软件使用 + #. HMAC 用作 RSA 数字签名外设 (RSA_DS) 的密钥 + #. HMAC 用于启用软禁用的 JTAG 接口 + + 第一种应用场景称为 **上行** 模式，后两种应用场景称为 **下行** 模式。 + +.. only:: not SOC_DIG_SIGN_SUPPORTED + + 此外，在 {IDF_TARGET_NAME} 上的 HMAC 有以下两种应用场景： + + #. HMAC 支持软件使用 + #. HMAC 用于启用软禁用的 JTAG 接口 + + 第一种应用场景称为 **上行** 模式，第二种应用场景称为 **下行** 模式。 HMAC 的 eFuse 密钥 ^^^^^^^^^^^^^^^^^^^ @@ -49,20 +60,35 @@ HMAC 的 eFuse 密钥 每个密钥都有相应的 eFuse 参数 **密钥功能 (key purpose)**，决定密钥应用于 HMAC 的哪种应用场景。 -.. list-table:: - :widths: 15 70 - :header-rows: 1 +.. only:: SOC_DIG_SIGN_SUPPORTED - * - 密钥功能 - - 应用场景 - * - 8 - - HMAC 支持软件使用 - * - 7 - - HMAC 用作 RSA 数字签名外设 (RSA_DS) 的密钥 - * - 6 - - HMAC 启用软禁用的 JTAG 接口 - * - 5 - - HMAC 既用作 RSA 数字签名外设 (RSA_DS) 的密钥，又用于启用 JTAG 接口 + .. list-table:: + :widths: 15 70 + :header-rows: 1 + + * - 密钥功能 + - 应用场景 + * - 8 + - HMAC 支持软件使用 + * - 7 + - HMAC 用作 RSA 数字签名外设 (RSA_DS) 的密钥 + * - 6 + - HMAC 启用软禁用的 JTAG 接口 + * - 5 + - HMAC 既用作 RSA 数字签名外设 (RSA_DS) 的密钥，又用于启用 JTAG 接口 + +.. only:: not SOC_DIG_SIGN_SUPPORTED + + .. list-table:: + :widths: 15 70 + :header-rows: 1 + + * - 密钥功能 + - 应用场景 + * - 8 + - HMAC 支持软件使用 + * - 5, 6 + - HMAC 用于启用软禁用的 JTAG 接口（HMAC 下行模式） 这样一来，可以确保密钥用于原定场景。 @@ -79,16 +105,18 @@ HMAC 支持软件使用 :cpp:func:`psa_mac_compute` 用于计算 HMAC，该函数接收一个不透明的 PSA 密钥，该密钥引用了包含密钥机密的 eFuse 密钥块，并且该密钥块的用途被设置为上行模式。 -HMAC 用作 RSA 数字签名外设 (RSA_DS) 的密钥 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. only:: SOC_DIG_SIGN_SUPPORTED -密钥功能值：7、5 + HMAC 用作 RSA 数字签名外设 (RSA_DS) 的密钥 + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -HMAC 可用作密钥派生函数，解码 RSA_DS 模块使用的私钥参数。在此情况下，硬件使用标准信息进行计算。在 HMAC 部分只需提供 eFuse 密钥块和功能；而在 RSA_DS 模块则还需要一些额外参数。 + 密钥功能值：7、5 -无论是密钥还是实际的 HMAC，都不会暴露在 HMAC 和 RSA_DS 模块之外。对 HMAC 的计算，以及将其传递给 RSA_DS 模块的过程，均在内部进行。 + HMAC 可用作密钥派生函数，解码 RSA_DS 模块使用的私钥参数。在此情况下，硬件使用标准信息进行计算。在 HMAC 部分只需提供 eFuse 密钥块和功能；而在 RSA_DS 模块则还需要一些额外参数。 -详情请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **RSA 数字签名外设 (RSA_DS)** [`PDF <{IDF_TARGET_TRM_CN_URL}#digsig>`__]。 + 无论是密钥还是实际的 HMAC，都不会暴露在 HMAC 和 RSA_DS 模块之外。对 HMAC 的计算，以及将其传递给 RSA_DS 模块的过程，均在内部进行。 + + 详情请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **RSA 数字签名外设 (RSA_DS)** [`PDF <{IDF_TARGET_TRM_CN_URL}#digsig>`__]。 .. _hmac_for_enabling_jtag: diff --git a/docs/zh_CN/api-reference/system/random.rst b/docs/zh_CN/api-reference/system/random.rst index c0c7f2680c4..d825f639ee3 100644 --- a/docs/zh_CN/api-reference/system/random.rst +++ b/docs/zh_CN/api-reference/system/random.rst @@ -3,7 +3,7 @@ :link_to_translation:`en:[English]` -{IDF_TARGET_RF_NAME: default="Wi-Fi 或蓝牙", esp32s2="Wi-Fi", esp32h2="蓝牙或 802.15.4 Thread/Zigbee", esp32c6="Wi-Fi 或蓝牙或 802.15.4 Thread/Zigbee", esp32c5="Wi-Fi 或蓝牙或 802.15.4 Thread/Zigbee"} +{IDF_TARGET_RF_NAME: default="Wi-Fi 或蓝牙", esp32s2="Wi-Fi", esp32h2="蓝牙或 802.15.4 Thread/Zigbee", esp32h4="蓝牙或 802.15.4 Thread/Zigbee", esp32c6="Wi-Fi 或蓝牙或 802.15.4 Thread/Zigbee", esp32c5="Wi-Fi 或蓝牙或 802.15.4 Thread/Zigbee"} {IDF_TARGET_RF_IS: default="已启用", esp32s2="已启用"} {IDF_TARGET_NAME} 中包含一个硬件随机数发生器 (RNG)，可以调用 API :cpp:func:`esp_random` 和 :cpp:func:`esp_fill_random` 从中获取随机数值。 diff --git a/docs/zh_CN/security/security-features-enablement-workflows.rst b/docs/zh_CN/security/security-features-enablement-workflows.rst index 6c45c5aa101..b9cf7eed45b 100644 --- a/docs/zh_CN/security/security-features-enablement-workflows.rst +++ b/docs/zh_CN/security/security-features-enablement-workflows.rst @@ -8,7 +8,7 @@ {IDF_TARGET_CRYPT_CNT:default="SPI_BOOT_CRYPT_CNT",esp32="FLASH_CRYPT_CNT"} {IDF_TARGET_CRYPT_CNT_MAX_VAL:default="7",esp32="127"} -{IDF_TARGET_SBV2_DEFAULT_SCHEME:default="RSA", esp32c2="ECDSA (V2)"} +{IDF_TARGET_SBV2_DEFAULT_SCHEME:default="RSA", esp32c2, esp32h4="ECDSA (V2)"} {IDF_TARGET_FLASH_ENC_ARGS:default="--aes-xts", esp32=""} 概述 diff --git a/docs/zh_CN/security/security.rst b/docs/zh_CN/security/security.rst index 2602ec01b14..7074329d8c3 100644 --- a/docs/zh_CN/security/security.rst +++ b/docs/zh_CN/security/security.rst @@ -190,7 +190,7 @@ JTAG - 如果启用了任一安全功能，则 JTAG 接口将保持禁用。更多详情请参阅 :ref:`jtag-debugging-security-features`。 - 如果不启用其他安全功能，也可以使用 :ref:`efuse_API` 禁用 JTAG 接口。 - :SOC_HMAC_SUPPORTED: - {IDF_TARGET_NAME} 支持软禁用 JTAG 接口，并且可以通过 HMAC 烧录密钥重新启用，请参阅 :ref:`hmac_for_enabling_jtag`。 + :SOC_HMAC_SUPPORTED: - {IDF_TARGET_NAME} 支持软禁用 JTAG 接口，并且可以通过 HMAC 烧录密钥重新启用，请参阅 :ref:`HMAC 启用 JTAG 接口 `。 UART 下载模式 ^^^^^^^^^^^^^^^^^^