diff --git a/docs/en/api-reference/peripherals/ds.rst b/docs/en/api-reference/peripherals/ds.rst index 6cac5199176..eb79d8c5f45 100644 --- a/docs/en/api-reference/peripherals/ds.rst +++ b/docs/en/api-reference/peripherals/ds.rst @@ -1,17 +1,21 @@ -Digital Signature (DS) -====================== +RSA Digital Signature Peripheral (RSA_DS) +========================================== :link_to_translation:`zh_CN:[中文]` -The Digital Signature (DS) module provides hardware acceleration of signing messages based on RSA. It uses pre-encrypted parameters to calculate a signature. The parameters are encrypted using HMAC as a key-derivation function. In turn, the HMAC uses eFuses as the input key. +<<<<<<< HEAD +The RSA Digital Signature Peripheral (RSA_DS) provides hardware acceleration of signing messages based on RSA. It uses pre-encrypted parameters to calculate a signature. The parameters are encrypted using HMAC as a key-derivation function. In turn, the HMAC uses eFuses as the input key. .. only:: SOC_KEY_MANAGER_SUPPORTED - On {IDF_TARGET_NAME}, the Digital Signature (DS) module can also use a key stored in the Key Manager instead of an eFuse key block. The AES encryption key can be directly deployed in the Key Manager with the type :cpp:enumerator:`ESP_KEY_MGR_DS_KEY`. Refer to :ref:`key-manager` for more details. + On {IDF_TARGET_NAME}, the RSA Digital Signature Peripheral (RSA_DS) can also use a key stored in the Key Manager instead of an eFuse key block. The AES encryption key can be directly deployed in the Key Manager with the type :cpp:enumerator:`ESP_KEY_MGR_DS_KEY`. Refer to :ref:`key-manager` for more details. The whole process happens in hardware so that neither the decryption key for the RSA parameters nor the input key for the HMAC key derivation function can be seen by the software while calculating the signature. +======= +The RSA Digital Signature Peripheral (RSA_DS) provides hardware acceleration of signing messages based on RSA. It uses pre-encrypted parameters to calculate a signature. The parameters are encrypted using HMAC as a key-derivation function. In turn, the HMAC uses eFuses as the input key. The whole process happens in hardware so that neither the decryption key for the RSA parameters nor the input key for the HMAC key derivation function can be seen by the software while calculating the signature. +>>>>>>> 81dc3a427c00 (docs(security): Standardize naming of digital signature hardware modules) -For more detailed information on the hardware involved in the signature calculation and the registers used, see **{IDF_TARGET_NAME} Technical Reference Manual** > **Digital Signature (DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. +For more detailed information on the hardware involved in the signature calculation and the registers used, see **{IDF_TARGET_NAME} Technical Reference Manual** > **RSA Digital Signature Peripheral (RSA_DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. Private Key Parameters @@ -24,14 +28,14 @@ Upon signature calculation invocation, the software only specifies which eFuse k Key Generation -------------- -Both the HMAC key and the RSA private key have to be created and stored before the DS peripheral can be used. This needs to be done in software on the {IDF_TARGET_NAME} or alternatively on a host. For this context, ESP-IDF provides :cpp:func:`esp_efuse_write_block` to set the HMAC key and :cpp:func:`esp_hmac_calculate` to encrypt the private RSA key parameters. +Both the HMAC key and the RSA private key have to be created and stored before the RSA_DS peripheral can be used. This needs to be done in software on the {IDF_TARGET_NAME} or alternatively on a host. For this context, ESP-IDF provides :cpp:func:`esp_efuse_write_block` to set the HMAC key and :cpp:func:`esp_hmac_calculate` to encrypt the private RSA key parameters. -You can find instructions on how to calculate and assemble the private key parameters in **{IDF_TARGET_NAME} Technical Reference Manual** > **Digital Signature (DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. +You can find instructions on how to calculate and assemble the private key parameters in **{IDF_TARGET_NAME} Technical Reference Manual** > **RSA Digital Signature Peripheral (RSA_DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. Signature Calculation with ESP-IDF ---------------------------------- -For more detailed information on the workflow and the registers used, see **{IDF_TARGET_NAME} Technical Reference Manual** > **Digital Signature (DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. +For more detailed information on the workflow and the registers used, see **{IDF_TARGET_NAME} Technical Reference Manual** > **RSA Digital Signature Peripheral (RSA_DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. Three parameters need to be prepared to calculate the digital signature: @@ -43,11 +47,11 @@ Three parameters need to be prepared to calculate the digital signature: Since the signature calculation takes some time, there are two possible API versions to use in ESP-IDF. The first one is :cpp:func:`esp_ds_sign` and simply blocks until the calculation is finished. If software needs to do something else during the calculation, :cpp:func:`esp_ds_start_sign` can be called, followed by periodic calls to :cpp:func:`esp_ds_is_busy` to check when the calculation has finished. Once the calculation has finished, :cpp:func:`esp_ds_finish_sign` can be called to get the resulting signature. -The APIs :cpp:func:`esp_ds_sign` and :cpp:func:`esp_ds_start_sign` calculate a plain RSA signature with the help of the DS peripheral. This signature must be converted to an appropriate format (e.g., PKCS#1 v1.5 or PSS) for use in TLS or other protocols. +The APIs :cpp:func:`esp_ds_sign` and :cpp:func:`esp_ds_start_sign` calculate a plain RSA signature with the help of the RSA_DS peripheral. This signature must be converted to an appropriate format (e.g., PKCS#1 v1.5 or PSS) for use in TLS or other protocols. .. note:: - This is only the basic DS building block; the message length is fixed. To create signatures of arbitrary messages, the input is normally a hash of the actual message, padded up to the required length. + This is only the basic RSA_DS building block; the message length is fixed. To create signatures of arbitrary messages, the input is normally a hash of the actual message, padded up to the required length. **PSA Crypto driver** @@ -55,26 +59,26 @@ The DS peripheral is also exposed via the **PSA Crypto RSA DS driver**, so you c .. _configure-the-ds-peripheral: -Configure the DS Peripheral for a TLS Connection ------------------------------------------------- +Configure the RSA_DS Peripheral for a TLS Connection +---------------------------------------------------- -The DS peripheral on {IDF_TARGET_NAME} chip must be configured before it can be used for a TLS connection. The configuration involves the following steps: +The RSA_DS peripheral on {IDF_TARGET_NAME} chip must be configured before it can be used for a TLS connection. The configuration involves the following steps: 1) Randomly generate a 256-bit value called the ``Initialization Vector`` (IV). 2) Randomly generate a 256-bit value called the ``HMAC_KEY``. 3) Calculate the encrypted private key parameters from the client private key (RSA) and the parameters generated in the above steps. -4) Then burn the 256-bit ``HMAC_KEY`` on the eFuse, which can only be read by the DS peripheral. +4) Then burn the 256-bit ``HMAC_KEY`` on the eFuse, which can only be read by the RSA_DS peripheral. -For more details, see **{IDF_TARGET_NAME} Technical Reference Manual** > **Digital Signature (DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. +For more details, see **{IDF_TARGET_NAME} Technical Reference Manual** > **RSA Digital Signature Peripheral (RSA_DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. -To configure the DS peripheral for development purposes, you can use the `esp-secure-cert-tool `_. +To configure the RSA_DS peripheral for development purposes, you can use the `esp-secure-cert-tool `_. -The encrypted private key parameters obtained after the DS peripheral configuration should be stored in flash. The application needs to read the DS data from flash (e.g. through the APIs provided by the `esp_secure_cert_mgr `_ component; see the `component/README `_ for more details). For using the DS peripheral with ESP-TLS, see :ref:`digital-signature-with-esp-tls`. +The encrypted private key parameters obtained after the RSA_DS peripheral configuration should be stored in flash. The application needs to read the RSA_DS data from flash (e.g. through the APIs provided by the `esp_secure_cert_mgr `_ component; see the `component/README `_ for more details). For using the RSA_DS peripheral with ESP-TLS, see :ref:`digital-signature-with-esp-tls`. -Using DS with PSA Crypto ------------------------- +Using RSA_DS with PSA Crypto +----------------------------- -To use the DS peripheral for signing or decryption in application code (outside of ESP-TLS), enable ``CONFIG_MBEDTLS_HARDWARE_RSA_DS_PERIPHERAL``. Populate an ``esp_ds_data_ctx_t`` with the encrypted key data (:cpp:type:`esp_ds_data_t`), the eFuse key block ID, and the RSA key length in bits. Ensure the ``rsa_length`` field of :cpp:type:`esp_ds_data_t` is set when the key is created (e.g. via :cpp:func:`esp_ds_encrypt_params` or the DS provisioning tool). Then wrap the context in an ``esp_rsa_ds_opaque_key_t``, import it as a PSA opaque key using ``PSA_KEY_LIFETIME_ESP_RSA_DS_VOLATILE``, and call ``psa_sign_hash()`` or ``psa_asymmetric_decrypt()``: +To use the RSA_DS peripheral for signing or decryption in application code (outside of ESP-TLS), enable ``CONFIG_MBEDTLS_HARDWARE_RSA_DS_PERIPHERAL``. Populate an ``esp_ds_data_ctx_t`` with the encrypted key data (:cpp:type:`esp_ds_data_t`), the eFuse key block ID, and the RSA key length in bits. Ensure the ``rsa_length`` field of :cpp:type:`esp_ds_data_t` is set when the key is created (e.g. via :cpp:func:`esp_ds_encrypt_params` or the RSA_DS provisioning tool). Then wrap the context in an ``esp_rsa_ds_opaque_key_t``, import it as a PSA opaque key using ``PSA_KEY_LIFETIME_ESP_RSA_DS_VOLATILE``, and call ``psa_sign_hash()`` or ``psa_asymmetric_decrypt()``: .. code-block:: c @@ -113,8 +117,8 @@ To use the DS peripheral for signing or decryption in application code (outside psa_destroy_key(key_id); -Example for SSL Mutual Authentication Using DS ----------------------------------------------- +Example for SSL Mutual Authentication Using RSA_DS +--------------------------------------------------- The SSL mutual authentication example that previously lived under ``examples/protocols/mqtt/ssl_ds`` is now shipped with the standalone `espressif/mqtt `__ component. Follow the component documentation to fetch the SSL DS example and build it together with ESP-MQTT. The example continues to use ``mqtt_client`` (implemented by ESP-MQTT) to connect to ``test.mosquitto.org`` over mutual-authenticated TLS, with the TLS portion handled by ESP-TLS. diff --git a/docs/en/api-reference/peripherals/ecdsa.rst b/docs/en/api-reference/peripherals/ecdsa.rst index 4d5ab165db8..bb2a572dbef 100644 --- a/docs/en/api-reference/peripherals/ecdsa.rst +++ b/docs/en/api-reference/peripherals/ecdsa.rst @@ -1,13 +1,13 @@ -Elliptic Curve Digital Signature Algorithm (ECDSA) -================================================== +ECDSA Digital Signature Peripheral (ECDSA_DS) +============================================== :link_to_translation:`zh_CN:[中文]` -The Elliptic Curve Digital Signature Algorithm (ECDSA) offers a variant of the Digital Signature Algorithm (DSA) which uses elliptic-curve cryptography. +The ECDSA Digital Signature Peripheral (ECDSA_DS) implements the Elliptic Curve Digital Signature Algorithm (ECDSA), a variant of the Digital Signature Algorithm (DSA) that uses elliptic-curve cryptography. -{IDF_TARGET_NAME}'s ECDSA peripheral provides a secure and efficient environment for computing ECDSA signatures. It offers fast computations while ensuring the confidentiality of the signing process to prevent information leakage. ECDSA private key used in the signing process is accessible only to the hardware peripheral, and it is not readable by software. +{IDF_TARGET_NAME}'s ECDSA_DS peripheral provides a secure and efficient environment for computing ECDSA signatures. It offers fast computations while ensuring the confidentiality of the signing process to prevent information leakage. ECDSA private key used in the signing process is accessible only to the hardware peripheral, and it is not readable by software. -ECDSA peripheral can help to establish **Secure Device Identity** for TLS mutual authentication and similar use-cases. +The ECDSA_DS peripheral can help to establish **Secure Device Identity** for TLS mutual authentication and similar use-cases. Supported Features ------------------ @@ -21,14 +21,14 @@ Supported Features :not SOC_ECDSA_SUPPORT_CURVE_P384: - Two hash algorithms for message hash in the ECDSA operation, namely SHA-224 and SHA-256 (FIPS PUB 180-4 specification) -ECDSA on {IDF_TARGET_NAME} --------------------------- +ECDSA_DS on {IDF_TARGET_NAME} +----------------------------- -On {IDF_TARGET_NAME}, the ECDSA module works with a secret key burnt into an eFuse block. +On {IDF_TARGET_NAME}, the ECDSA_DS module works with a secret key burnt into an eFuse block. .. only:: SOC_KEY_MANAGER_SUPPORTED - On {IDF_TARGET_NAME}, the ECDSA module also supports storing a secret key in the Key Manager. Refer to :ref:`key-manager` for more details. + On {IDF_TARGET_NAME}, the ECDSA_DS module also supports storing a secret key in the Key Manager. Refer to :ref:`key-manager` for more details. This key is made completely inaccessible (default mode) for any resources outside the cryptographic modules, thus avoiding key leakage. @@ -70,13 +70,13 @@ Using eFuses to store the ECDSA key: .. note:: - Five physical eFuse blocks can be used as keys for the ECDSA module: block 4 ~ block 8. E.g., for block 4 (which is the first key block) , the argument should be ``BLOCK_KEY0``. + Five physical eFuse blocks can be used as keys for the ECDSA_DS module: block 4 ~ block 8. E.g., for block 4 (which is the first key block) , the argument should be ``BLOCK_KEY0``. .. only:: not SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK .. note:: - Six physical eFuse blocks can be used as keys for the ECDSA module: block 4 ~ block 9. E.g., for block 4 (which is the first key block) , the argument should be ``BLOCK_KEY0``. + Six physical eFuse blocks can be used as keys for the ECDSA_DS module: block 4 ~ block 9. E.g., for block 4 (which is the first key block) , the argument should be ``BLOCK_KEY0``. .. only:: SOC_KEY_MANAGER_SUPPORTED @@ -116,11 +116,11 @@ Following code snippet uses :cpp:func:`esp_efuse_write_key` to set physical key .. only:: esp32h2 - The ECDSA peripheral of the ESP32-H2 supports both ECDSA-P192 and ECDSA-P256 operations. However, starting with ESP32-H2 revision 1.2, only ECDSA-P256 operations are enabled by default. You can enable ECDSA-P192 operations using the following configuration options: + The ECDSA_DS peripheral of the ESP32-H2 supports both ECDSA-P192 and ECDSA-P256 operations. However, starting with ESP32-H2 revision 1.2, only ECDSA-P256 operations are enabled by default. You can enable ECDSA-P192 operations using the following configuration options: .. only:: not esp32h2 - The ECDSA peripheral of {IDF_TARGET_NAME} supports both ECDSA-P192 and ECDSA-P256 operations, but only ECDSA-P256 operations are enabled by default. You can enable ECDSA-P192 operations through the following configuration options: + The ECDSA_DS peripheral of {IDF_TARGET_NAME} supports both ECDSA-P192 and ECDSA-P256 operations, but only ECDSA-P256 operations are enabled by default. You can enable ECDSA-P192 operations through the following configuration options: - :ref:`CONFIG_ESP_ECDSA_ENABLE_P192_CURVE` enables support for ECDSA-P192 curve operations, allowing the device to perform ECDSA operations with both 192-bit and 256-bit curves. However, if ECDSA-P192 operations have already been permanently disabled during eFuse write protection, enabling this option can not re-enable ECDSA-P192 curve operations. @@ -131,7 +131,7 @@ Following code snippet uses :cpp:func:`esp_efuse_write_key` to set physical key Deterministic Signature Generation ----------------------------------- - The ECDSA peripheral of {IDF_TARGET_NAME} also supports generation of deterministic signatures using deterministic derivation of the parameter K as specified in the `RFC 6979 `_ section 3.2. + The ECDSA_DS peripheral of {IDF_TARGET_NAME} also supports generation of deterministic signatures using deterministic derivation of the parameter K as specified in the `RFC 6979 `_ section 3.2. Non-Determinisitic Signature Generation --------------------------------------- @@ -139,16 +139,16 @@ Non-Determinisitic Signature Generation Dependency on TRNG ^^^^^^^^^^^^^^^^^^ -ECDSA peripheral relies on the hardware True Random Number Generator (TRNG) for its internal entropy requirement for generating non-deterministic signatures. During ECDSA signature creation, the algorithm requires a random integer to be generated as specified in the `RFC 6090 `_ section 5.3.2. +The ECDSA_DS peripheral relies on the hardware True Random Number Generator (TRNG) for its internal entropy requirement for generating non-deterministic signatures. During ECDSA signature creation, the algorithm requires a random integer to be generated as specified in the `RFC 6090 `_ section 5.3.2. Please ensure that hardware :doc:`RNG <../system/random>` is enabled before starting ECDSA computations (primarily signing) in the application. Application Outline ------------------- -Please refer to the :ref:`ecdsa-peri-with-esp-tls` guide for details on how-to use ECDSA peripheral for establishing a mutually authenticated TLS connection. +Please refer to the :ref:`ecdsa-peri-with-esp-tls` guide for details on how-to use the ECDSA_DS peripheral for establishing a mutually authenticated TLS connection. -The ECDSA peripheral in Mbed TLS stack is integrated by overriding the ECDSA signing and verifying APIs. Please note that, the ECDSA peripheral does not support all curves or hash algorithms, and hence for cases where the hardware requirements are not met, the implementation falls back to the software. +The ECDSA_DS peripheral in Mbed TLS stack is integrated by overriding the ECDSA signing and verifying APIs. Please note that, the ECDSA_DS peripheral does not support all curves or hash algorithms, and hence for cases where the hardware requirements are not met, the implementation falls back to the software. For a particular TLS context, additional APIs have been supplied to populate certain fields (e.g., private key ctx) to differentiate routing to hardware. ESP-TLS layer integrates these APIs internally and hence no additional work is required at the application layer. However, for custom use-cases please refer to API details below. diff --git a/docs/en/api-reference/peripherals/hmac.rst b/docs/en/api-reference/peripherals/hmac.rst index 876a2c64d65..066cd891bc3 100644 --- a/docs/en/api-reference/peripherals/hmac.rst +++ b/docs/en/api-reference/peripherals/hmac.rst @@ -37,7 +37,7 @@ This key can be made completely inaccessible for any resources outside the crypt Furthermore, {IDF_TARGET_NAME} has three different application scenarios for its HMAC module: #. HMAC is generated for software use -#. HMAC is used as a key for the Digital Signature (DS) module +#. HMAC is used as a key for the RSA Digital Signature Peripheral (RSA_DS) module #. 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. @@ -58,11 +58,11 @@ Each key has a corresponding eFuse parameter **key purpose** determining for whi * - 8 - HMAC generated for software use * - 7 - - HMAC used as a key for the Digital Signature (DS) module + - HMAC used as a key for the RSA Digital Signature Peripheral (RSA_DS) module * - 6 - HMAC used for enabling the soft-disabled JTAG interface * - 5 - - HMAC both as a key for the DS module and for enabling JTAG + - HMAC both as a key for the RSA_DS module and for enabling JTAG This is to prevent the usage of a key for a different function than originally intended. @@ -79,14 +79,14 @@ 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 Digital Signature -^^^^^^^^^^^^^^^^^^^^^^^^^^ +HMAC for RSA Digital Signature +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Key purpose values: 7, 5 -The HMAC can be used as a key derivation function to decrypt private key parameters which are used by the 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 Digital Signature component in that case. +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. -Neither the key nor the actual HMAC is ever exposed outside the HMAC module and DS component. The calculation of the HMAC and its handover to the DS component happen internally. +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** > **Digital Signature (DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. diff --git a/docs/en/api-reference/protocols/esp_http_client.rst b/docs/en/api-reference/protocols/esp_http_client.rst index dcac58612b1..5510148a669 100644 --- a/docs/en/api-reference/protocols/esp_http_client.rst +++ b/docs/en/api-reference/protocols/esp_http_client.rst @@ -46,10 +46,10 @@ A secure element (ATECC608) can be also used for the underlying TLS connection i .. only:: SOC_ECDSA_SUPPORTED - Use ECDSA Peripheral for TLS - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Use ECDSA Digital Signature Peripheral (ECDSA_DS) for TLS + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - The ECDSA peripheral can be used for the underlying TLS connection in the HTTP client connection. Please refer to the **ECDSA Peripheral with ESP-TLS** section in the :doc:`ESP-TLS documentation ` for more details. The HTTP client can be configured to use ECDSA peripheral as follows: + The ECDSA Digital Signature Peripheral (ECDSA_DS) can be used for the underlying TLS connection in the HTTP client connection. Please refer to the **ECDSA Digital Signature Peripheral (ECDSA_DS) with ESP-TLS** section in the :doc:`ESP-TLS documentation ` for more details. The HTTP client can be configured to use the ECDSA_DS peripheral as follows: .. code-block:: c diff --git a/docs/en/api-reference/protocols/esp_tls.rst b/docs/en/api-reference/protocols/esp_tls.rst index a91a8572294..8f5f5b13b7c 100644 --- a/docs/en/api-reference/protocols/esp_tls.rst +++ b/docs/en/api-reference/protocols/esp_tls.rst @@ -247,9 +247,9 @@ To enable the secure element support, and use it in your project for TLS connect Digital Signature with ESP-TLS ------------------------------ - ESP-TLS provides support for using the Digital Signature (DS) with {IDF_TARGET_NAME}. Use of the DS for TLS is supported only when ESP-TLS is used with MbedTLS (default stack) as its underlying SSL/TLS stack. For more details on Digital Signature, please refer to the :doc:`Digital Signature (DS) `. The technical details of Digital Signature such as how to calculate private key parameters can be found in **{IDF_TARGET_NAME} Technical Reference Manual** > **Digital Signature (DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. The DS peripheral must be configured before it can be used to perform Digital Signature, see :ref:`configure-the-ds-peripheral`. + ESP-TLS provides support for using the RSA Digital Signature Peripheral (RSA_DS) with {IDF_TARGET_NAME}. Use of the RSA_DS for TLS is supported only when ESP-TLS is used with MbedTLS (default stack) as its underlying SSL/TLS stack. For more details on the RSA_DS, please refer to the :doc:`RSA Digital Signature Peripheral (RSA_DS) `. The technical details such as how to calculate private key parameters can be found in **{IDF_TARGET_NAME} Technical Reference Manual** > **RSA Digital Signature Peripheral (RSA_DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. The RSA_DS peripheral must be configured before it can be used to perform RSA digital signature, see :ref:`configure-the-ds-peripheral`. - The DS peripheral must be initialized with the required encrypted private key parameters, which are obtained when the DS peripheral is configured. ESP-TLS internally initializes the DS peripheral when provided with the required DS context, i.e., DS parameters. Please see the below code snippet for passing the DS context to the ESP-TLS context. The DS context passed to the ESP-TLS context should not be freed till the TLS connection is deleted. + The RSA_DS peripheral must be initialized with the required encrypted private key parameters, which are obtained when the RSA_DS peripheral is configured. ESP-TLS internally initializes the RSA_DS peripheral when provided with the required DS context, i.e., DS parameters. Please see the below code snippet for passing the DS context to the ESP-TLS context. The DS context passed to the ESP-TLS context should not be freed till the TLS connection is deleted. .. code-block:: c @@ -265,20 +265,20 @@ To enable the secure element support, and use it in your project for TLS connect .. note:: - When using Digital Signature for the TLS connection, along with the other required params, only the client certification (`clientcert_buf`) and the DS params (`ds_data`) are required and the client key (`clientkey_buf`) can be set to NULL. + When using the RSA_DS for the TLS connection, along with the other required params, only the client certification (`clientcert_buf`) and the DS params (`ds_data`) are required and the client key (`clientkey_buf`) can be set to NULL. - * A mutual-authentication example that utilizes the DS peripheral is shipped with the standalone `espressif/mqtt `__ component and internally relies on ESP-TLS for the TLS connection. Follow the component documentation to fetch and build that example. + * A mutual-authentication example that utilizes the RSA_DS peripheral is shipped with the standalone `espressif/mqtt `__ component and internally relies on ESP-TLS for the TLS connection. Follow the component documentation to fetch and build that example. .. only:: SOC_ECDSA_SUPPORTED .. _ecdsa-peri-with-esp-tls: - ECDSA Peripheral with ESP-TLS - ----------------------------- + ECDSA Digital Signature Peripheral (ECDSA_DS) with ESP-TLS + ----------------------------------------------------------- - ESP-TLS provides support for using the ECDSA peripheral with {IDF_TARGET_NAME}. The use of ECDSA peripheral is supported only when ESP-TLS is used with MbedTLS as its underlying SSL/TLS stack. The ECDSA private key should be present in the eFuse for using the ECDSA peripheral. Please refer to :doc:`ECDSA Guide <../peripherals/ecdsa>` for programming the ECDSA key in the eFuse. + ESP-TLS provides support for using the ECDSA Digital Signature Peripheral (ECDSA_DS) with {IDF_TARGET_NAME}. The use of the ECDSA_DS peripheral is supported only when ESP-TLS is used with MbedTLS as its underlying SSL/TLS stack. The ECDSA private key should be present in the eFuse for using the ECDSA_DS peripheral. Please refer to :doc:`ECDSA Digital Signature Peripheral (ECDSA_DS) <../peripherals/ecdsa>` for programming the ECDSA key in the eFuse. - This will enable the use of ECDSA peripheral for private key operations. As the client private key is already present in the eFuse, it need not be supplied to the :cpp:type:`esp_tls_cfg_t` structure. Please see the below code snippet for enabling the use of ECDSA peripheral for a given ESP-TLS connection. + This will enable the use of the ECDSA_DS peripheral for private key operations. As the client private key is already present in the eFuse, it need not be supplied to the :cpp:type:`esp_tls_cfg_t` structure. Please see the below code snippet for enabling the use of the ECDSA_DS peripheral for a given ESP-TLS connection. .. code-block:: c @@ -292,7 +292,7 @@ To enable the secure element support, and use it in your project for TLS connect .. note:: - When using ECDSA peripheral with TLS, only ``MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`` ciphersuite is supported. If using TLS v1.3, ``MBEDTLS_TLS1_3_AES_128_GCM_SHA256`` ciphersuite is supported. + When using the ECDSA_DS peripheral with TLS, only ``MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`` ciphersuite is supported. If using TLS v1.3, ``MBEDTLS_TLS1_3_AES_128_GCM_SHA256`` ciphersuite is supported. .. _esp_tls_client_session_tickets: diff --git a/docs/en/security/secure-boot-v2.rst b/docs/en/security/secure-boot-v2.rst index 829844c2994..4edba2e0bae 100644 --- a/docs/en/security/secure-boot-v2.rst +++ b/docs/en/security/secure-boot-v2.rst @@ -531,7 +531,7 @@ Restrictions After Secure Boot Is Enabled .. only:: SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED - When Secure Boot is enabled, the ECDSA curve mode becomes write-protected. This means that if the curve mode was not previously set to use the ECDSA-P192 key before enabling Secure Boot, it will no longer be possible to configure or use the ECDSA-P192 curve on the ECDSA peripheral afterward. + When Secure Boot is enabled, the ECDSA curve mode becomes write-protected. This means that if the curve mode was not previously set to use the ECDSA-P192 key before enabling Secure Boot, it will no longer be possible to configure or use the ECDSA-P192 curve on the ECDSA_DS peripheral afterward. Burning read-protected keys ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/en/security/security.rst b/docs/en/security/security.rst index 8070c4b7804..f6d97911da7 100644 --- a/docs/en/security/security.rst +++ b/docs/en/security/security.rst @@ -3,7 +3,7 @@ Security Overview {IDF_TARGET_CIPHER_SCHEME:default="RSA", esp32h2="RSA or ECDSA", esp32p4="RSA or ECDSA", esp32c5="RSA or ECDSA", esp32c61="ECDSA", esp32h21="RSA or ECDSA"} -{IDF_TARGET_SIG_PERI:default="DS", esp32h2="DS or ECDSA", esp32p4="DS or ECDSA", esp32c5="DS or ECDSA"} +{IDF_TARGET_SIG_PERI:default="RSA_DS", esp32h2="RSA_DS or ECDSA_DS", esp32p4="RSA_DS or ECDSA_DS", esp32c5="RSA_DS or ECDSA_DS", esp32c61="ECDSA_DS"} :link_to_translation:`zh_CN:[中文]` @@ -85,21 +85,21 @@ Flash Encryption Best Practices Device Identity ~~~~~~~~~~~~~~~ - The Digital Signature peripheral in {IDF_TARGET_NAME} produces hardware-accelerated RSA digital signatures with the assistance of HMAC, without the RSA private key being accessible by software. This allows the private key to be kept secured on the device without anyone other than the device hardware being able to access it. + The RSA Digital Signature Peripheral (RSA_DS) in {IDF_TARGET_NAME} produces hardware-accelerated RSA digital signatures with the assistance of HMAC, without the RSA private key being accessible by software. This allows the private key to be kept secured on the device without anyone other than the device hardware being able to access it. .. only:: SOC_ECDSA_SUPPORTED - {IDF_TARGET_NAME} also supports ECDSA peripheral for generating hardware-accelerated ECDSA digital signatures. ECDSA private key can be directly programmed in an eFuse block and marked as read protected from the software. + {IDF_TARGET_NAME} also supports the ECDSA Digital Signature Peripheral (ECDSA_DS) for generating hardware-accelerated ECDSA digital signatures. ECDSA private key can be directly programmed in an eFuse block and marked as read protected from the software. {IDF_TARGET_SIG_PERI} peripheral can help to establish the **Secure Device Identity** to the remote endpoint, e.g., in the case of TLS mutual authentication based on the {IDF_TARGET_CIPHER_SCHEME} cipher scheme. .. only:: not SOC_ECDSA_SUPPORTED - Please refer to the :doc:`../api-reference/peripherals/ds` for detailed documentation. + Please refer to the :doc:`RSA Digital Signature Peripheral (RSA_DS) <../api-reference/peripherals/ds>` for detailed documentation. .. only:: SOC_ECDSA_SUPPORTED - Please refer to the :doc:`../api-reference/peripherals/ecdsa` and :doc:`../api-reference/peripherals/ds` guides for detailed documentation. + Please refer to the :doc:`ECDSA Digital Signature Peripheral (ECDSA_DS) <../api-reference/peripherals/ecdsa>` and :doc:`RSA Digital Signature Peripheral (RSA_DS) <../api-reference/peripherals/ds>` guides for detailed documentation. .. only:: SOC_KEY_MANAGER_SUPPORTED