diff --git a/docs/en/api-reference/protocols/esp_crt_bundle.rst b/docs/en/api-reference/protocols/esp_crt_bundle.rst index 2f3237c651..b4efc35df0 100644 --- a/docs/en/api-reference/protocols/esp_crt_bundle.rst +++ b/docs/en/api-reference/protocols/esp_crt_bundle.rst @@ -87,19 +87,18 @@ Cross-Signed Certificate Support Overview ^^^^^^^^ -When the configuration option :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_CROSS_SIGNED_VERIFY` is enabled, -the ESP x509 Certificate Bundle API adds support for verifying certificate chains that include cross-signed root certificates. -This feature allows the verification process to dynamically select candidate Certificate Authorities (CAs) from the bundle, -even when the certificate chain contains cross-signed roots, improving interoperability with a wider range of server certificates. +When the configuration option :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_CROSS_SIGNED_VERIFY` is enabled, the ESP x509 Certificate Bundle API adds support for verifying certificate chains that include cross-signed root certificates. -With this functionality enabled, certificate verification is performed in a manner equivalent to the default mbedTLS behaviour, -ensuring compatibility and robust validation for cross-signed chains. +This feature allows the verification process to dynamically select candidate Certificate Authorities (CAs) from the bundle, even when the certificate chain contains cross-signed roots, improving interoperability with a wider range of server certificates. + +With this functionality enabled, certificate verification is performed in a manner equivalent to the default mbedTLS behavior, ensuring compatibility and robust validation for cross-signed chains. .. note:: - Enabling cross-signed certificate support increases run-time heap utilisation by approximately 700 bytes, but reduces the flash footprint as the bundle size is reduced. + Enabling cross-signed certificate support increases run-time heap utilization by approximately 700 bytes, but reduces the flash footprint as the bundle size is reduced. Key Points: + - The bundle can act as a dynamic CA store, providing candidate root certificates during the handshake. - The verification callback uses the issuer information from the certificate chain to locate and provide matching root certificates from the bundle. - This is especially useful for environments where cross-signing is common, such as during root CA transitions. @@ -107,8 +106,7 @@ Key Points: Usage ^^^^^ -No additional application changes are required beyond enabling :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_CROSS_SIGNED_VERIFY` in your project configuration. -The bundle will automatically provide candidate CAs during the TLS handshake. +No additional application changes are required beyond enabling :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_CROSS_SIGNED_VERIFY` in your project configuration. The bundle will automatically provide candidate CAs during the TLS handshake. .. note:: diff --git a/docs/zh_CN/api-reference/protocols/esp_crt_bundle.rst b/docs/zh_CN/api-reference/protocols/esp_crt_bundle.rst index ef9790e6c8..ee7d67c078 100644 --- a/docs/zh_CN/api-reference/protocols/esp_crt_bundle.rst +++ b/docs/zh_CN/api-reference/protocols/esp_crt_bundle.rst @@ -81,6 +81,37 @@ ESP x509 证书包 API 提供了一种简便的方法,帮助你安装自定义 证书包会与 Mozilla 的 NSS 根证书商店定期同步。在 ESP-IDF 的次要版本或补丁版本中,为了保证兼容性,会将上游证书包中已弃用的证书添加到弃用列表。如有需要,可以通过 :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEPRECATED_LIST` 将弃用证书加入默认证书包。这些弃用证书将在下一个 ESP-IDF 主要版本中移除。 +交叉签名证书支持 +---------------- + +概述 +^^^^ + +启用配置选项 :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_CROSS_SIGNED_VERIFY` 时,ESP x509 证书包 API 将支持验证包含交叉签名根证书的证书链。 + +即使证书链中包含交叉签名根证书,验证过程中也能从证书包中智能匹配候选的证书颁发机构 (CA),从而提高与各类服务器证书的互操作性。 + +启用该功能后,证书验证逻辑与默认的 mbedTLS 行为一致,能够确保与交叉签名证书链兼容,且验证过程稳健可靠。 + +.. note:: + + 启用交叉签名证书支持功能后,运行时的堆内存使用量将增加约 700 字节,但由于证书包体积减小,flash 占用会降低。 + +关键点: + +- 证书包可作为动态 CA 存储,在握手过程中提供候选的根证书; +- 验证回调函数会使用证书链中的颁发者信息,从证书包中定位并提供匹配的根证书; +- 该功能在交叉签名较为常见的场景中能够提供帮助,例如根 CA 切换期间。 + +使用方法 +^^^^^^^^ + +除了在项目配置中启用 :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_CROSS_SIGNED_VERIFY` 外,应用无需额外更改。握手过程中,证书包会自动提供候选的 CA。 + +.. note:: + + 如果启用了 :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_CROSS_SIGNED_VERIFY`,其内部会使用 ``MBEDTLS_X509_TRUSTED_CERT_CALLBACK``。在此情况下,用户 **不应** 自行提供受信任证书回调函数,因为证书包会自动处理。 + 应用示例 ---------