diff --git a/components/esp_wifi/include/esp_wifi.h b/components/esp_wifi/include/esp_wifi.h index b92353b157..32160a9f0b 100644 --- a/components/esp_wifi/include/esp_wifi.h +++ b/components/esp_wifi/include/esp_wifi.h @@ -1131,6 +1131,19 @@ esp_err_t esp_wifi_get_inactive_time(wifi_interface_t ifx, uint16_t *sec); */ esp_err_t esp_wifi_statis_dump(uint32_t modules); +/** + * @brief Disable PMF configuration for specified interface + * + * @attention This API should be called after esp_wifi_set_config() and before esp_wifi_start(). + * + * @param ifx Interface to be configured. + * + * @return + * - ESP_OK: succeed + * - others: failed + */ +esp_err_t esp_wifi_disable_pmf_config(wifi_interface_t ifx); + #ifdef __cplusplus } #endif diff --git a/components/esp_wifi/include/esp_wifi_types.h b/components/esp_wifi/include/esp_wifi_types.h index 244f6089be..10b4340642 100644 --- a/components/esp_wifi/include/esp_wifi_types.h +++ b/components/esp_wifi/include/esp_wifi_types.h @@ -207,7 +207,7 @@ typedef enum { /** Configuration structure for Protected Management Frame */ typedef struct { - bool capable; /**< Advertizes support for Protected Management Frame. Device will prefer to connect in PMF mode if other device also advertizes PMF capability. */ + bool capable; /**< Deprecated variable. Device will always connect in PMF mode if other device also advertizes PMF capability. */ bool required; /**< Advertizes that Protected Management Frame is required. Device will not associate to non-PMF capable devices. */ } wifi_pmf_config_t; diff --git a/components/esp_wifi/lib b/components/esp_wifi/lib index d5bf5a6da7..3712c028c0 160000 --- a/components/esp_wifi/lib +++ b/components/esp_wifi/lib @@ -1 +1 @@ -Subproject commit d5bf5a6da74462e920e6f6f19815588fe455ef99 +Subproject commit 3712c028c0c0791008dbf7317df9d6218211f7e7 diff --git a/docs/en/api-guides/wifi.rst b/docs/en/api-guides/wifi.rst index a449b3839d..51ca7b34b0 100644 --- a/docs/en/api-guides/wifi.rst +++ b/docs/en/api-guides/wifi.rst @@ -1417,13 +1417,34 @@ An attacker can use eavesdropping and packet injection to send spoofed (de)authe PMF provides protection against these attacks by encrypting unicast management frames and providing integrity checks for broadcast management frames. These include deauthentication, disassociation and robust management frames. It also provides Secure Association (SA) teardown mechanism to prevent spoofed association/authentication frames from disconnecting already connected clients. -{IDF_TARGET_NAME} supports the following three modes of operation with respect to PMF. +There are 3 types of PMF configuration modes on both Station and AP side - + - PMF Optional + - PMF Required + - PMF Disabled - - PMF not supported: In this mode, {IDF_TARGET_NAME} indicates to AP that it is not capable of supporting management protection during association. In effect, security in this mode will be equivalent to that in traditional mode. - - PMF capable, but not required: In this mode, {IDF_TARGET_NAME} indicates to AP that it is capable of supporting PMF. The management protection will be used if AP mandates PMF or is at least capable of supporting PMF. - - PMF capable and required: In this mode, {IDF_TARGET_NAME} will only connect to AP, if AP supports PMF. If not, {IDF_TARGET_NAME} will refuse to connect to the AP. +Depending on the PMF configuration on Station and AP side, the resulting connection will behave differently. Below table summarises all possible outcomes. -:cpp:func:`esp_wifi_set_config` can be used to configure PMF mode by setting appropriate flags in `pmf_cfg` parameter. Currently, PMF is supported only in Station mode. ++--------------+------------------------+---------------------------+ +| STA Setting | AP Setting | Outcome | ++==============+========================+===========================+ +| PMF Optional | PMF Optional/Required | Mgmt Frames Protected | ++--------------+------------------------+---------------------------+ +| PMF Optional | PMF Disabled | Mgmt Frames Not Protected | ++--------------+------------------------+---------------------------+ +| PMF Required | PMF Optional/Required | Mgmt Frames Protected | ++--------------+------------------------+---------------------------+ +| PMF Required | PMF Disabled | STA refuses Connection | ++--------------+------------------------+---------------------------+ +| PMF Disabled | PMF Optional/Disabled | Mgmt Frames Not Protected | ++--------------+------------------------+---------------------------+ +| PMF Disabled | PMF Required | AP refuses Connection | ++--------------+------------------------+---------------------------+ + +{IDF_TARGET_NAME} supports PMF only in Station mode. Station defaults to PMF Optional mode and disabling PMF is not possible. For even higher security, PMF Required mode can be enabled by setting the ``required`` flag in `pmf_cfg` while using the :cpp:func:`esp_wifi_set_config` API. This will result in Station only connecting to a PMF enabled AP and rejecting all other AP's. + +.. attention:: + + ``capable`` flag in `pmf_cfg` is deprecated and set to true internally. This is to take the additional security benefit of PMF whenever possible. WPA3-Personal diff --git a/examples/wifi/getting_started/station/main/station_example_main.c b/examples/wifi/getting_started/station/main/station_example_main.c index f8d91e26e1..e478a4fc2b 100644 --- a/examples/wifi/getting_started/station/main/station_example_main.c +++ b/examples/wifi/getting_started/station/main/station_example_main.c @@ -96,11 +96,6 @@ void wifi_init_sta(void) * However these modes are deprecated and not advisable to be used. Incase your Access point * doesn't support WPA2, these mode can be enabled by commenting below line */ .threshold.authmode = WIFI_AUTH_WPA2_PSK, - - .pmf_cfg = { - .capable = true, - .required = false - }, }, }; ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA) ); diff --git a/examples/wifi/iperf/main/cmd_wifi.c b/examples/wifi/iperf/main/cmd_wifi.c index 08ef097e36..e5f5369f1d 100644 --- a/examples/wifi/iperf/main/cmd_wifi.c +++ b/examples/wifi/iperf/main/cmd_wifi.c @@ -148,7 +148,6 @@ static bool wifi_cmd_sta_join(const char* ssid, const char* pass) int bits = xEventGroupWaitBits(wifi_event_group, CONNECTED_BIT, 0, 1, 0); wifi_config_t wifi_config = { 0 }; - wifi_config.sta.pmf_cfg.capable = true; strlcpy((char*) wifi_config.sta.ssid, ssid, sizeof(wifi_config.sta.ssid)); if (pass) { diff --git a/examples/wifi/wifi_eap_fast/main/wifi_eap_fast_main.c b/examples/wifi/wifi_eap_fast/main/wifi_eap_fast_main.c index 477c08cd29..bcb190c7dd 100644 --- a/examples/wifi/wifi_eap_fast/main/wifi_eap_fast_main.c +++ b/examples/wifi/wifi_eap_fast/main/wifi_eap_fast_main.c @@ -89,12 +89,6 @@ static void initialise_wifi(void) wifi_config_t wifi_config = { .sta = { .ssid = EXAMPLE_WIFI_SSID, -#if defined(CONFIG_EXAMPLE_WPA3_ENTERPRISE) - .pmf_cfg = { - .capable = true, - .required = false - }, -#endif }, }; ESP_LOGI(TAG, "Setting WiFi configuration SSID %s...", wifi_config.sta.ssid);