Merge branch 'bugfix/ignore_pmf_capable_flag_v4.4' into 'release/v4.4'

Always connect Station in PMF mode if possible (Backport v4.4) See merge request espressif/esp-idf!17036
2024-09-20 00:36:01 -04:00 · 2022-03-07 16:24:44 +08:00 · 2022-03-07 16:24:44 +08:00 · dc7cb6de4b
commit dc7cb6de4b
parent 92a67e0fff 659306b243
9 changed files with 28 additions and 51 deletions
--- a/components/esp_wifi/include/esp_wifi_types.h
+++ b/components/esp_wifi/include/esp_wifi_types.h
@ -215,7 +215,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;

--- a/components/esp_wifi/lib
+++ b/components/esp_wifi/lib
@ -1 +1 @@
-Subproject commit 5a4e7d21a14522f8b584832ec6b89626b7916b50
+Subproject commit 5a0d2aee49633b1a0c0374c2a01ed8c2a10e2fe4
--- a/components/wpa_supplicant/esp_supplicant/src/esp_dpp.c
+++ b/components/wpa_supplicant/esp_supplicant/src/esp_dpp.c
@ -170,7 +170,6 @@ static int esp_dpp_handle_config_obj(struct dpp_authentication *auth,
            os_memcpy(wifi_cfg->sta.password, conf->passphrase,
                      sizeof(wifi_cfg->sta.password));
        if (conf->akm == DPP_AKM_PSK_SAE) {
-            wifi_cfg->sta.pmf_cfg.capable = true;
            wifi_cfg->sta.pmf_cfg.required = true;
        }
    }
--- a/docs/en/api-guides/wifi-security.rst
+++ b/docs/en/api-guides/wifi-security.rst
@ -25,31 +25,12 @@ 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.

-API & Usage
-+++++++++++
+There are 3 types of PMF configuration modes on both Station and AP side -
+ - PMF Optional
+ - PMF Required
+ - PMF Disabled

-: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.
-While setting up a Station, configure PMF using two flags ``capable`` and ``required`` like below.
-
-   .. code-block:: c
-
-    wifi_config_t wifi_config = {
-        .sta = {
-             .ssid = EXAMPLE_WIFI_SSID,
-             .password = EXAMPLE_WIFI_PASSWORD,
-             .pmf_cfg = {
-                .capable = true,
-                .required = false
-             }
-        }
-    };
-
-{IDF_TARGET_NAME} supports three modes of PMF by combination of these two flags -
- - PMF Optional : ``.capable = true, .required = false``
- - PMF Required : ``.capable = true, .required = true``
- - PMF Disabled : ``.capable = false, .required = false``
-
- Depending on what AP side PMF Mode is, the resulting connnection will behave differently. The table below summarises all possible outcomes -
+Depending on the PMF configuration on Station and AP side, the resulting connection will behave differently. Below table summarises all possible outcomes.

 +--------------+------------------------+---------------------------+
 | STA Setting  | AP Setting             |  Outcome                  |
@ -67,7 +48,27 @@ While setting up a Station, configure PMF using two flags ``capable`` and ``requ
 | PMF Disabled |  PMF Required          | AP refuses Connection     |
 +--------------+------------------------+---------------------------+

-PMF Optional Mode, which is shown in the example of ``wifi_confit_t``, is suggested to be used in all Station configurations. This is to take the additional security benefit of PMF whenever possible without breaking connections with legacy AP's.
+API & Usage
+++++++++++
+
+{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. An example of this configuration is given below.
+
+   .. code-block:: c
+
+    wifi_config_t wifi_config = {
+        .sta = {
+             .ssid = EXAMPLE_WIFI_SSID,
+             .password = EXAMPLE_WIFI_PASSWORD,
+             .pmf_cfg = {
+                .required = true
+             }
+        }
+    };
+
+.. 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
 -------------
--- a/examples/bluetooth/nimble/bleprph_wifi_coex/main/main.c
+++ b/examples/bluetooth/nimble/bleprph_wifi_coex/main/main.c
@ -123,11 +123,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) );
--- a/examples/protocols/static_ip/main/static_ip_example_main.c
+++ b/examples/protocols/static_ip/main/static_ip_example_main.c
@ -141,11 +141,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) );
--- 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) );
--- a/examples/wifi/iperf/main/cmd_wifi.c
+++ b/examples/wifi/iperf/main/cmd_wifi.c
@ -161,7 +161,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) {
--- a/examples/wifi/wifi_enterprise/main/wifi_enterprise_main.c
+++ b/examples/wifi/wifi_enterprise/main/wifi_enterprise_main.c
@ -122,15 +122,8 @@ 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
 #if defined (CONFIG_EXAMPLE_WPA3_192BIT_ENTERPRISE)
            .pmf_cfg = {
-                .capable = true,
                .required = true
            },
 #endif