docs/zh_CN/api-guides/wifi-security.rst
:link_to_translation:en:[English]
除传统安全方法 (WEP/WPA-TKIP/WPA2-CCMP) 外，{IDF_TARGET_NAME} Wi-Fi 还支持最先进的安全协议，即受保护的管理帧 (PMF)、第三代 Wi-Fi 访问保护和基于机会性无线加密技术的增强型开放式™ Wi-Fi 安全协议。WPA3 能更好地保护隐私，并在已知针对传统模式的攻击下具有更强的鲁棒性。增强型开放式™ Wi-Fi 安全协议可以在用户连接到无需认证的开放（公共）Wi-Fi 时，确保用户设备安全，并保护隐私。
简介 ++++++++++++
Wi-Fi 网络中，非 AP 设备使用如信标、探测、（解）身份验证和（断）关联等管理帧，扫描并连接到 AP。不同于数据帧，管理帧在传输时不会加密。
由此，攻击者可以利用窃听和数据包注入，在适当时机发送伪造的（解）身份验证或（断）关联管理帧，发起拒绝服务 (DoS) 和中间人攻击等攻击。
PMF 通过加密单播管理帧以及为广播管理帧提供完整性检查，来应对上述解身份验证、解关联和鲁棒管理帧等攻击。此外，PMF 还提供了安全关联 (SA) 拆除机制，防止伪造的关联或验证帧使已连接的客户端断开连接。
station 和 AP 支持三类 PMF 配置模式：
API 及用法 ++++++++++++
在 station 模式和 SoftAP 模式下，{IDF_TARGET_NAME} 都支持 PMF，两者均默认配置为可选 PMF。为了更高的安全性，可以在使用 :cpp:func:esp_wifi_set_config API 时设置 pmf_cfg 中的 required 标志，启用强制 PMF 模式。启用后，设备将仅连接到启用了 PMF 的设备，并拒绝其他设备发起的连接。使用 :cpp:func:esp_wifi_disable_pmf_config API 可以禁用可选 PMF 配置模式。如果在 WPA3 或 WPA2/WPA3 混合模式下启动了 SoftAP 模式，尝试禁用 PMF 会导致错误。
.. attention::
为最大限度地利用 PMF 的额外安全性优势，已弃用 ``pmf_cfg`` 中的 ``capable`` 标志，并在内部设置为 ``true``。
简介 ++++++++
企业级 Wi-Fi (Wi-Fi Enterprise) 为企业无线网络提供安全认证机制。该机制基于 IEEE 802.1X 标准运作，并依赖 RADIUS 服务器在设备连接到接入点 (AP) 之前进行用户身份验证。根据所使用的可扩展认证协议 (EAP) 方法，认证可以基于用户凭证（用户名和密码）、数字证书，或两者结合。
当 {IDF_TARGET_NAME} 以 station 模式连接企业级 AP 时，会发起认证请求。AP 会将该请求转发给配置的 RADIUS 服务器，由其根据所选 EAP 方法和参数对设备进行验证。
.. note::
{IDF_TARGET_NAME} 仅在 station 模式下支持企业级 Wi-Fi。
企业级 WPA2 和企业级 WPA3 ++++++++++++++++++++++++++++++
{IDF_TARGET_NAME} 支持 企业级 WPA2 (WPA2-Enterprise) 和 企业级 WPA3 (WPA3-Enterprise)。
企业级 WPA2 使用 802.1X/EAP 进行身份验证，并依赖安全的凭证或证书。为建立安全连接，AP 与 station 会协商并选定适当的加密套件。{IDF_TARGET_NAME} 支持以下内容：
USE_MBEDTLS_CRYPTO 后可使用 mbedtls 支持的其他 cipher suite企业级 WPA3 在企业级 WPA2 的基础上加强了安全性，并对所有 WPA3 连接增加两项强制要求：必须启用受保护管理帧 (PMF)，并强制执行服务器证书验证。
此外，企业级 WPA3 还支持 192 位最低强度安全模式 (Suite B)，提供更高的加密强度。
SOC_WIFI_GCMP_SUPPORT 的芯片。CONFIG_ESP_WIFI_SUITE_B_192。支持的 EAP 方法 +++++++++++++++++++++
{IDF_TARGET_NAME} 支持多种企业级认证的 EAP 方法。不同方法可能需要不同的配置参数，如 SSID、身份标识、用户名/密码、CA 证书或客户端证书等。
支持以下 EAP 方法：
EAP-TLS
基于证书的认证方式，需要提供 SSID 和 EAP 身份；通过客户端证书进行设备认证。
PEAP
一种受保护的 EAP 方法，需要提供用户名和密码。
EAP-TTLS
一种基于凭证的认证方式。服务器认证为必选；用户认证取决于 Phase 2 方法。通常需要提供用户名和密码。支持的 Phase 2 方法包括：
EAP-FAST
基于受保护访问凭证 (PAC) 的认证方法，需要身份标识和密码。使用 EAP-FAST 时需要 禁用 :ref:CONFIG_ESP_WIFI_MBEDTLS_TLS_CLIENT。
示例 ++++++++
:example:wifi/wifi_eap_fast
演示如何使用 EAP-FAST 将 {IDF_TARGET_NAME} 连接到企业级 Wi-Fi，包括 CA 证书安装、凭证配置、启用企业级模式以及连接 AP。
:example:wifi/wifi_enterprise
演示使用 EAP-TLS、EAP-PEAP 和 EAP-TTLS 连接企业级 Wi-Fi。有关使用 OpenSSL 生成证书及运行示例的说明，请参考 :example_file:wifi/wifi_enterprise/README.md。
简介 ++++++++++++
第三代 Wi-Fi 访问保护 (WPA3) 是一组强化的 Wi-Fi 接入安全性标准，旨在取代当前的 WPA2 标准。WPA3 包含了新的功能和属性，可以提供更显著的保护效果，应对不同类型的攻击。相比 WPA2-Personal，WPA 3-Personal 有以下改进：
{IDF_TARGET_NAME} 的 station 模式还支持以下额外的 Wi-Fi CERTIFIED WPA3™ 功能：
禁用过渡：WPA3 为客户端定义了过渡模式。该模式下，即使网络中的某些 AP 不支持最强的安全模式，客户端也能正常接入网络。客户端通常会默认将网络配置文件配置为过渡模式。然而，这类客户端可能会遭受主动降级攻击，即攻击者会引导客户端使用强度较低的安全模式，以利用该模式的漏洞。为减轻这种攻击的影响，WPA3 引入了禁用过渡功能。当连接到某个网络时，若该网络已全面支持更高级的安全模式，则支持客户端从过渡模式切换到“纯粹”模式。请在 :cpp:type:wifi_sta_config_t 中启用 :cpp:type:transition_disable，为 {IDF_TARGET_NAME} 的 station 模式启用此功能。
SAE 公钥 (PK)：由于小型公共网络中的密码与多个用户共享，攻击者可能更容易破解密码，发动伪装双子攻击。为阻止这类攻击，个人级 WPA3 引入了 SAE-PK 扩展认证机制。SAE-PK 认证交换与常规 SAE 交换非常相似，唯一区别在于 AP 会向客户端发送数字签名。客户端基于密码指纹验证 AP 断言的公钥，并使用公钥验证签名。因此，即使攻击者知道密码，也不知道生成有效签名所需的私钥，避免客户端遭受伪装双子攻击。请启用 :ref:CONFIG_ESP_WIFI_ENABLE_SAE_PK，并在 :cpp:type:wifi_sta_config_t 中使用 :cpp:type:sae_pk_mode 进行相应配置，为 {IDF_TARGET_NAME} 的 station 模式添加 SAE PK 支持。
SAE PWE Methods: {IDF_TARGET_NAME} 的 station 和 SoftAP 模式都支持 SAE 密码元素的推导方法 Hunting And Pecking 和 Hash to Element (H2E)。H2E 所需迭代次数较少，因此计算效率更高，还可以减轻侧通道攻击的风险。这些方法可以分别在 station 模式和 SoftAP 中通过参数 :cpp:type:sae_pwe_h2e 配置，其中 :cpp:type:wifi_sta_config_t 用于 station 模式，:cpp:type:wifi_ap_config_t 用于 SoftAP 模式。请使用配置选项 :cpp:enumerator:WPA3_SAE_PWE_BOTH 启用 Hunting And Pecking 和 H2E 方法。
请参阅 Wi-Fi 联盟官网的 安全性 <https://www.wi-fi.org/discover-wi-fi/security>_ 部分，了解更多详情。
在 {IDF_TARGET_NAME} 上设置 WPA3 ++++++++++++++++++++++++++++++++++++++
配置选项 :ref:CONFIG_ESP_WIFI_ENABLE_WPA3_SAE 用于在 station 上启用或禁用 WPA3，该选项默认启用，如果禁用，则 {IDF_TARGET_NAME} 无法建立 WPA3 连接。Wi-Fi 组件中还提供了配置选项 :ref:CONFIG_ESP_WIFI_SOFTAP_SAE_SUPPORT，用于在 SoftAP 上启用或禁用 WPA3。此外，由于 WPA3 协议强制使用 PMF，因此，station 和 SoftAP 的 PMF 模式均默认为可选 PMF。可以使用 Wi-Fi 配置选项将 PMF 模式配置为强制 PMF。WPA3 SoftAP 仅支持使用强制 PMF 模式，如无特别指定，则将在 NVS 中隐式配置并存储该模式。
要了解如何设置 PMF 模式，请参阅 受保护的管理帧 (PMF)_。
在为 WPA3-Personal station 配置完所需设置后，应用程序开发人员无需再对 AP 的底层安全模式进行操作。从安全性来看，WPA3-Personal 是目前支持的最高级别协议，因此只要该协议可用，设备就会自动选择将该协议用于连接。例如，如果将 AP 配置为 WPA3 过渡模式，即同时支持 WPA2 和 WPA3，station 将根据以上设置连接 WPA3。
在为 WPA3-Personal 的 SoftAP 模式配置完所需设置后，应用程序开发人员必须在 :cpp:type:wifi_ap_config_t 中的 authmode 设置 WIFI_AUTH_WPA3_PSK，启动以 WPA3 安全模式运行的 AP。也可将 SoftAP 配置为使用 WIFI_AUTH_WPA2_WPA3_PSK 的混合模式。
注意，启用 :ref:CONFIG_ESP_WIFI_SOFTAP_SAE_SUPPORT 时，二进制文件大小将增加约 6.5 千字节。
简介 ++++++++++++
增强型开放式™ Wi-Fi 安全协议为连接到开放（公共）Wi-Fi 的用户提供更高的安全性和隐私保护，尤其适用于无需验证用户身份或无法分发凭证的场景。在此协议下，每位用户都可以获得独特的个人加密密钥，保障用户设备与 Wi-Fi 网络间的数据交换安全。同时，受保护的管理帧还进一步增强了接入点与用户设备之间管理流量的安全性。增强型开放式™ Wi-Fi 安全协议基于机会性无线加密 (OWE) 实现，OWE 过渡模式可以从开放的未加密 WLAN 完美过渡到 OWE WLAN，不会对终端用户体验造成不良影响。
.. note::
{IDF_TARGET_NAME} 仅在 station 模式下支持增强型开放式™ Wi-Fi 安全协议。
在 {IDF_TARGET_NAME} 上设置 OWE ++++++++++++++++++++++++++++++++++++++
配置选项 :ref:CONFIG_ESP_WIFI_ENABLE_WPA3_OWE_STA 和 :cpp:type:wifi_sta_config_t 中的配置参数 :cpp:type:owe_enabled 可以为 station 模式启用 OWE 支持。除上述配置外，请将 :cpp:type:wifi_scan_threshold_t 中的 authmode 设置为 WIFI_AUTH_OPEN 以使用 OWE 过渡模式。