From 3d85e81be2d7c9332dc4c1661e670953c177c859 Mon Sep 17 00:00:00 2001 From: Shreyas Sheth Date: Fri, 18 Aug 2023 11:46:34 +0530 Subject: [PATCH 1/2] docs(wifi): Update wifi and wifi security documentation and bugfixes 1. Update documentation for WPA3 Enterprise and WPA3 Enterprise 192-bit mode 2. Update documentation for WPA3 OWE and OWE transition mode 3. Update documentation related to SAE PK, SAE PWE and Transition Disable 4. Update documnetation for wifi connect API 5. Fix config paramter information for wifi scan start 6. Fix documentation related to scan threshold config setting 7. Replace ESP_ERR_WIFI_ARG error code as ESP_ERR_INVALID_ARG 8. Update documentation for 802.11R Fast transition 9. Fix sta connecting with wpa security in enterprise mode --- components/esp_wifi/include/esp_mesh.h | 6 +- .../esp_wifi/include/esp_mesh_internal.h | 2 +- .../esp_wifi/include/esp_private/wifi.h | 8 +- components/esp_wifi/include/esp_wifi.h | 42 +++++----- components/esp_wifi/include/esp_wifi_types.h | 37 +++++---- components/esp_wifi/lib | 2 +- .../esp_supplicant/include/esp_wpa2.h | 8 +- docs/en/api-guides/wifi-security.rst | 82 +++++++++---------- docs/en/api-guides/wifi.rst | 4 +- docs/zh_CN/api-guides/wifi.rst | 4 +- 10 files changed, 95 insertions(+), 100 deletions(-) diff --git a/components/esp_wifi/include/esp_mesh.h b/components/esp_wifi/include/esp_mesh.h index 4a94511b62e..28a4561fe4f 100644 --- a/components/esp_wifi/include/esp_mesh.h +++ b/components/esp_wifi/include/esp_mesh.h @@ -1414,7 +1414,7 @@ esp_err_t esp_mesh_set_parent(const wifi_config_t *parent, const mesh_addr_t *pa * @return * - ESP_OK * - ESP_ERR_WIFI_NOT_INIT - * - ESP_ERR_WIFI_ARG + * - ESP_ERR_INVALID_ARG * - ESP_ERR_WIFI_FAIL */ esp_err_t esp_mesh_scan_get_ap_ie_len(int *len); @@ -1431,7 +1431,7 @@ esp_err_t esp_mesh_scan_get_ap_ie_len(int *len); * @return * - ESP_OK * - ESP_ERR_WIFI_NOT_INIT - * - ESP_ERR_WIFI_ARG + * - ESP_ERR_INVALID_ARG * - ESP_ERR_WIFI_FAIL */ esp_err_t esp_mesh_scan_get_ap_record(wifi_ap_record_t *ap_record, void *buffer); @@ -1520,7 +1520,7 @@ esp_err_t esp_mesh_switch_channel(const uint8_t *new_bssid, int csa_newchan, int * @return * - ESP_OK * - ESP_ERR_WIFI_NOT_INIT - * - ESP_ERR_WIFI_ARG + * - ESP_ERR_INVALID_ARG */ esp_err_t esp_mesh_get_router_bssid(uint8_t *router_bssid); diff --git a/components/esp_wifi/include/esp_mesh_internal.h b/components/esp_wifi/include/esp_mesh_internal.h index af602bb5480..ad54ce87038 100644 --- a/components/esp_wifi/include/esp_mesh_internal.h +++ b/components/esp_wifi/include/esp_mesh_internal.h @@ -126,7 +126,7 @@ typedef struct { * @return * - ESP_OK * - ESP_FAIL - * - ESP_ERR_WIFI_ARG + * - ESP_ERR_INVALID_ARG */ esp_err_t esp_mesh_set_beacon_interval(int interval_ms); diff --git a/components/esp_wifi/include/esp_private/wifi.h b/components/esp_wifi/include/esp_private/wifi.h index 7b2a7ef4851..4da66239272 100644 --- a/components/esp_wifi/include/esp_private/wifi.h +++ b/components/esp_wifi/include/esp_private/wifi.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -132,7 +132,7 @@ void esp_wifi_internal_free_rx_buffer(void* buffer); * @return * - ESP_OK : Successfully transmit the buffer to wifi driver * - ESP_ERR_NO_MEM: out of memory - * - ESP_ERR_WIFI_ARG: invalid argument + * - ESP_ERR_INVALID_ARG: invalid argument * - ESP_ERR_WIFI_IF : WiFi interface is invalid * - ESP_ERR_WIFI_CONN : WiFi interface is not created, e.g. send the data to STA while WiFi mode is AP mode * - ESP_ERR_WIFI_NOT_STARTED : WiFi is not started @@ -171,7 +171,7 @@ typedef void (*wifi_netstack_buf_free_cb_t)(void *netstack_buf); * @return * - ESP_OK : Successfully transmit the buffer to wifi driver * - ESP_ERR_NO_MEM: out of memory - * - ESP_ERR_WIFI_ARG: invalid argument + * - ESP_ERR_INVALID_ARG: invalid argument * - ESP_ERR_WIFI_IF : WiFi interface is invalid * - ESP_ERR_WIFI_CONN : WiFi interface is not created, e.g. send the data to STA while WiFi mode is AP mode * - ESP_ERR_WIFI_NOT_STARTED : WiFi is not started @@ -417,7 +417,7 @@ esp_err_t esp_wifi_internal_set_log_level(wifi_log_level_t level); * @return * - ESP_OK: succeed * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init - * - ESP_ERR_WIFI_ARG: invalid argument + * - ESP_ERR_INVALID_ARG: invalid argument */ esp_err_t esp_wifi_internal_set_log_mod(wifi_log_module_t module, uint32_t submodule, bool enable); diff --git a/components/esp_wifi/include/esp_wifi.h b/components/esp_wifi/include/esp_wifi.h index bff91afd221..8ba4ec5190e 100644 --- a/components/esp_wifi/include/esp_wifi.h +++ b/components/esp_wifi/include/esp_wifi.h @@ -344,9 +344,9 @@ esp_err_t esp_wifi_restore(void); * @attention 3. The scanning triggered by esp_wifi_scan_start() will not be effective until connection between ESP32 and the AP is established. * If ESP32 is scanning and connecting at the same time, ESP32 will abort scanning and return a warning message and error * number ESP_ERR_WIFI_STATE. - * If you want to do reconnection after ESP32 received disconnect event, remember to add the maximum retry time, otherwise the called - * scan will not work. This is especially true when the AP doesn't exist, and you still try reconnection after ESP32 received disconnect - * event with the reason code WIFI_REASON_NO_AP_FOUND. + * @attention 4. This API attempts to connect to an Access Point (AP) only once. To enable reconnection in case of a connection failure, please use + * the 'failure_retry_cnt' feature in the 'wifi_sta_config_t'. Users are suggested to implement reconnection logic in their application + * for scenarios where the specified AP does not exist, or reconnection is desired after the device has received a disconnect event. * * @return * - ESP_OK: succeed @@ -401,7 +401,10 @@ esp_err_t esp_wifi_deauth_sta(uint16_t aid); * @attention The values of maximum active scan time and passive scan time per channel are limited to 1500 milliseconds. * Values above 1500ms may cause station to disconnect from AP and are not recommended. * - * @param config configuration of scanning + * @param config configuration settings for scanning, if set to NULL default settings will be used + * of which default values are show_hidden:false, scan_type:active, scan_time.active.min:0, + * scan_time.active.max:120 miliseconds, scan_time.passive:360 miliseconds + * * @param block if block is true, this API will block the caller until the scan is done, otherwise * it will return immediately * @@ -785,7 +788,7 @@ esp_err_t esp_wifi_set_promiscuous_ctrl_filter(const wifi_promiscuous_filter_t * * @return * - ESP_OK: succeed * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init - * - ESP_ERR_WIFI_ARG: invalid argument + * - ESP_ERR_INVALID_ARG: invalid argument */ esp_err_t esp_wifi_get_promiscuous_ctrl_filter(wifi_promiscuous_filter_t *filter); @@ -932,7 +935,7 @@ esp_err_t esp_wifi_set_vendor_ie_cb(esp_vendor_ie_cb_t cb, void *ctx); * - ESP_OK: succeed * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start - * - ESP_ERR_WIFI_ARG: invalid argument, e.g. parameter is out of range + * - ESP_ERR_INVALID_ARG: invalid argument, e.g. parameter is out of range */ esp_err_t esp_wifi_set_max_tx_power(int8_t power); @@ -945,7 +948,7 @@ esp_err_t esp_wifi_set_max_tx_power(int8_t power); * - ESP_OK: succeed * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start - * - ESP_ERR_WIFI_ARG: invalid argument + * - ESP_ERR_INVALID_ARG: invalid argument */ esp_err_t esp_wifi_get_max_tx_power(int8_t *power); @@ -974,7 +977,7 @@ esp_err_t esp_wifi_set_event_mask(uint32_t mask); * @return * - ESP_OK: succeed * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init - * - ESP_ERR_WIFI_ARG: invalid argument + * - ESP_ERR_INVALID_ARG: invalid argument */ esp_err_t esp_wifi_get_event_mask(uint32_t *mask); @@ -994,7 +997,7 @@ esp_err_t esp_wifi_get_event_mask(uint32_t *mask); * the system sequence number. * Generally, if esp_wifi_80211_tx is called before the Wi-Fi connection has been set up, both * en_sys_seq==true and en_sys_seq==false are fine. However, if the API is called after the Wi-Fi - * connection has been set up, en_sys_seq must be true, otherwise ESP_ERR_WIFI_ARG is returned. + * connection has been set up, en_sys_seq must be true, otherwise ESP_ERR_INVALID_ARG is returned. * * @return * - ESP_OK: success @@ -1066,7 +1069,7 @@ esp_err_t esp_wifi_set_csi(bool en); * @return * - ESP_OK: succeed * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init - * - ESP_ERR_WIFI_ARG: Invalid argument, e.g. parameter is NULL, invalid GPIO number etc + * - ESP_ERR_INVALID_ARG: Invalid argument, e.g. parameter is NULL, invalid GPIO number etc */ esp_err_t esp_wifi_set_ant_gpio(const wifi_ant_gpio_config_t *config); @@ -1078,7 +1081,7 @@ esp_err_t esp_wifi_set_ant_gpio(const wifi_ant_gpio_config_t *config); * @return * - ESP_OK: succeed * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init - * - ESP_ERR_WIFI_ARG: invalid argument, e.g. parameter is NULL + * - ESP_ERR_INVALID_ARG: invalid argument, e.g. parameter is NULL */ esp_err_t esp_wifi_get_ant_gpio(wifi_ant_gpio_config_t *config); @@ -1091,7 +1094,7 @@ esp_err_t esp_wifi_get_ant_gpio(wifi_ant_gpio_config_t *config); * @return * - ESP_OK: succeed * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init - * - ESP_ERR_WIFI_ARG: Invalid argument, e.g. parameter is NULL, invalid antenna mode or invalid GPIO number + * - ESP_ERR_INVALID_ARG: Invalid argument, e.g. parameter is NULL, invalid antenna mode or invalid GPIO number */ esp_err_t esp_wifi_set_ant(const wifi_ant_config_t *config); @@ -1103,7 +1106,7 @@ esp_err_t esp_wifi_set_ant(const wifi_ant_config_t *config); * @return * - ESP_OK: succeed * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init - * - ESP_ERR_WIFI_ARG: invalid argument, e.g. parameter is NULL + * - ESP_ERR_INVALID_ARG: invalid argument, e.g. parameter is NULL */ esp_err_t esp_wifi_get_ant(wifi_ant_config_t *config); @@ -1136,7 +1139,7 @@ int64_t esp_wifi_get_tsf_time(wifi_interface_t interface); * - ESP_OK: succeed * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start - * - ESP_ERR_WIFI_ARG: invalid argument, For Station, if sec is less than 3. For SoftAP, if sec is less than 10. + * - ESP_ERR_INVALID_ARG: invalid argument, For Station, if sec is less than 3. For SoftAP, if sec is less than 10. */ esp_err_t esp_wifi_set_inactive_time(wifi_interface_t ifx, uint16_t sec); @@ -1150,7 +1153,7 @@ esp_err_t esp_wifi_set_inactive_time(wifi_interface_t ifx, uint16_t sec); * - ESP_OK: succeed * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start - * - ESP_ERR_WIFI_ARG: invalid argument + * - ESP_ERR_INVALID_ARG: invalid argument */ esp_err_t esp_wifi_get_inactive_time(wifi_interface_t ifx, uint16_t *sec); @@ -1166,16 +1169,17 @@ 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 Set RSSI threshold below which APP will get an event + * @brief Set RSSI threshold, if average rssi gets lower than threshold, WiFi task will post event WIFI_EVENT_STA_BSS_RSSI_LOW. * - * @attention This API needs to be called every time after WIFI_EVENT_STA_BSS_RSSI_LOW event is received. + * @attention If the user wants to receive another WIFI_EVENT_STA_BSS_RSSI_LOW event after receiving one, this API needs to be + * called again with an updated/same RSSI threshold. * * @param rssi threshold value in dbm between -100 to 0 * * @return * - ESP_OK: succeed * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init - * - ESP_ERR_WIFI_ARG: invalid argument + * - ESP_ERR_INVALID_ARG: invalid argument */ esp_err_t esp_wifi_set_rssi_threshold(int32_t rssi); @@ -1337,8 +1341,6 @@ esp_err_t esp_wifi_sta_get_aid(uint16_t *aid); * * @param[out] phymode store the negotiated phymode. * - * @attention Operation phy mode, BIT[5]: indicate whether LR enabled, BIT[0-4]: wifi_phy_mode_t - * * @return * - ESP_OK: succeed */ diff --git a/components/esp_wifi/include/esp_wifi_types.h b/components/esp_wifi/include/esp_wifi_types.h index 70588553d79..5c2d7cb192d 100644 --- a/components/esp_wifi/include/esp_wifi_types.h +++ b/components/esp_wifi/include/esp_wifi_types.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -267,23 +267,24 @@ typedef struct { /** @brief STA configuration settings for the ESP32 */ typedef struct { - uint8_t ssid[32]; /**< SSID of target AP. */ - uint8_t password[64]; /**< Password of target AP. */ - wifi_scan_method_t scan_method; /**< do all channel scan or fast scan */ - bool bssid_set; /**< whether set MAC address of target AP or not. Generally, station_config.bssid_set needs to be 0; and it needs to be 1 only when users need to check the MAC address of the AP.*/ - uint8_t bssid[6]; /**< MAC address of target AP*/ - uint8_t channel; /**< channel of target AP. Set to 1~13 to scan starting from the specified channel before connecting to AP. If the channel of AP is unknown, set it to 0.*/ - uint16_t listen_interval; /**< Listen interval for ESP32 station to receive beacon when WIFI_PS_MAX_MODEM is set. Units: AP beacon intervals. Defaults to 3 if set to 0. */ - wifi_sort_method_t sort_method; /**< sort the connect AP in the list by rssi or security mode */ - wifi_scan_threshold_t threshold; /**< When sort_method is set, only APs which have an auth mode that is more secure than the selected auth mode and a signal stronger than the minimum RSSI will be used. */ - wifi_pmf_config_t pmf_cfg; /**< Configuration for Protected Management Frame. Will be advertized in RSN Capabilities in RSN IE. */ - uint32_t rm_enabled:1; /**< Whether Radio Measurements are enabled for the connection */ - uint32_t btm_enabled:1; /**< Whether BSS Transition Management is enabled for the connection */ - uint32_t mbo_enabled:1; /**< Whether MBO is enabled for the connection */ - uint32_t transition_disable:1; /**< Whether to enable transition disable feature */ - uint32_t reserved:28; /**< Reserved for future feature set */ - wifi_sae_pwe_method_t sae_pwe_h2e; /**< Whether SAE hash to element is enabled */ - uint8_t failure_retry_cnt; /**< Number of connection retries station will do before moving to next AP. scan_method should be set as WIFI_ALL_CHANNEL_SCAN to use this config. Note: Enabling this may cause connection time to increase incase best AP doesn't behave properly. */ + uint8_t ssid[32]; /**< SSID of target AP. */ + uint8_t password[64]; /**< Password of target AP. */ + wifi_scan_method_t scan_method; /**< do all channel scan or fast scan */ + bool bssid_set; /**< whether set MAC address of target AP or not. Generally, station_config.bssid_set needs to be 0; and it needs to be 1 only when users need to check the MAC address of the AP.*/ + uint8_t bssid[6]; /**< MAC address of target AP*/ + uint8_t channel; /**< channel of target AP. Set to 1~13 to scan starting from the specified channel before connecting to AP. If the channel of AP is unknown, set it to 0.*/ + uint16_t listen_interval; /**< Listen interval for ESP32 station to receive beacon when WIFI_PS_MAX_MODEM is set. Units: AP beacon intervals. Defaults to 3 if set to 0. */ + wifi_sort_method_t sort_method; /**< sort the connect AP in the list by rssi or security mode */ + wifi_scan_threshold_t threshold; /**< When scan_threshold is set, only APs which have an auth mode that is more secure than the selected auth mode and a signal stronger than the minimum RSSI will be used. */ + wifi_pmf_config_t pmf_cfg; /**< Configuration for Protected Management Frame. Will be advertised in RSN Capabilities in RSN IE. */ + uint32_t rm_enabled:1; /**< Whether Radio Measurements are enabled for the connection */ + uint32_t btm_enabled:1; /**< Whether BSS Transition Management is enabled for the connection */ + uint32_t mbo_enabled:1; /**< Whether MBO is enabled for the connection */ + uint32_t transition_disable:1; /**< Whether to enable transition disable feature */ + uint32_t reserved:28; /**< Reserved for future feature set */ + wifi_sae_pwe_method_t sae_pwe_h2e; /**< Configuration for SAE PWE derivation method */ + uint8_t failure_retry_cnt; /**< Number of connection retries station will do before moving to next AP. scan_method should be set as WIFI_ALL_CHANNEL_SCAN to use this config. + Note: Enabling this may cause connection time to increase incase best AP doesn't behave properly. */ } wifi_sta_config_t; /** @brief Configuration data for ESP32 AP or STA. diff --git a/components/esp_wifi/lib b/components/esp_wifi/lib index 56d90884814..6fd120a997d 160000 --- a/components/esp_wifi/lib +++ b/components/esp_wifi/lib @@ -1 +1 @@ -Subproject commit 56d90884814a4c92b614abde60926d4e2faa84c0 +Subproject commit 6fd120a997d581bbee290b1c6732c93869feef99 diff --git a/components/wpa_supplicant/esp_supplicant/include/esp_wpa2.h b/components/wpa_supplicant/esp_supplicant/include/esp_wpa2.h index 41a6a7d685c..098514f0b1e 100644 --- a/components/wpa_supplicant/esp_supplicant/include/esp_wpa2.h +++ b/components/wpa_supplicant/esp_supplicant/include/esp_wpa2.h @@ -32,8 +32,8 @@ extern "C" { /** * @brief Enable wpa2 enterprise authentication. * - * @attention 1. wpa2 enterprise authentication can only be used when ESP32 station is enabled. - * @attention 2. wpa2 enterprise authentication can only support TLS, PEAP-MSCHAPv2 and TTLS-MSCHAPv2 method. + * @attention 1. wpa2 enterprise authentication can only be used when station mode is enabled. + * @attention 2. wpa2 enterprise authentication supports EAP-FAST, TLS, PEAP, TTLS(EAP, MSCHAPv2, MSCHAP, PAP, CHAP) methods. * * @return * - ESP_OK: succeed. @@ -44,8 +44,8 @@ esp_err_t esp_wifi_sta_wpa2_ent_enable(void); /** * @brief Disable wpa2 enterprise authentication. * - * @attention 1. wpa2 enterprise authentication can only be used when ESP32 station is enabled. - * @attention 2. wpa2 enterprise authentication can only support TLS, PEAP-MSCHAPv2 and TTLS-MSCHAPv2 method. + * @attention 1. wpa2 enterprise authentication can only be used when station mode is enabled. + * @attention 2. wpa2 enterprise authentication supports EAP-FAST, TLS, PEAP, TTLS(EAP, MSCHAPv2, MSCHAP, PAP, CHAP) methods. * * @return * - ESP_OK: succeed. diff --git a/docs/en/api-guides/wifi-security.rst b/docs/en/api-guides/wifi-security.rst index 77f1bdc6245..d577b4f052d 100644 --- a/docs/en/api-guides/wifi-security.rst +++ b/docs/en/api-guides/wifi-security.rst @@ -6,7 +6,7 @@ Wi-Fi Security - Support for Protected Management Frames (PMF) - Support for WPA3-Personal -In addition to traditional security methods (WEP/WPA-TKIP/WPA2-CCMP), {IDF_TARGET_NAME} Wi-Fi supports state-of-the-art security protocols, namely Protected Management Frames based on 802.11w standard and Wi-Fi Protected Access 3 (WPA3-Personal). Together, PMF and WPA3 provide better privacy and robustness against known attacks on traditional modes. +In addition to traditional security methods (WEP/WPA-TKIP/WPA2-CCMP), {IDF_TARGET_NAME} Wi-Fi supports state-of-the-art security protocols, namely Protected Management, Wi-Fi Protected Access 3. WPA3 provides better privacy and robustness against known attacks on traditional modes. Protected Management Frames (PMF) --------------------------------- @@ -15,60 +15,46 @@ Introduction ++++++++++++ In Wi-Fi, management frames such as beacons, probes, (de)authentication, (dis)association are used by non-AP stations to scan and connect to an AP. Unlike data frames, these frames are sent unencrypted. -An attacker can use eavesdropping and packet injection to send spoofed (de)authentication/(dis)association frames at the right time, leading to the following attacks in case of unprotected management frame exchanges. - - - DOS attack on one or all clients in the range of the attacker. - - Tearing down existing association on AP side by sending association request. - - Forcing a client to perform 4-way handshake again in case PSK is compromised in order to get PTK. - - Getting SSID of hidden network from association request. - - Launching man-in-the-middle attack by forcing clients to deauth from legitimate AP and associating to a rogue one. +An attacker can use eavesdropping and packet injection to send spoofed (de)authentication/(dis)association frames at the right time, leading to attacks such as Denial-of-Service (DOS) and man-in-the-middle 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. -There are 3 types of PMF configuration modes on both Station and AP side - +There are 3 types of PMF configuration modes on Station side - - PMF Optional - PMF Required - PMF Disabled -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 | -+==============+========================+===========================+ -| 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 | -+--------------+------------------------+---------------------------+ - 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 - } - } - }; +{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. +WiFi Enterprise +--------------------------------- + +Introduction +++++++++++++ + +Enterprise security is the secure authentication mechanism for enterprise wireless networks. It uses RADIUS server for authentication of network users before connecting to the Access Point. The authentication process is based on 802.1X policy and comes with different Extended Authentication Protocol (EAP) methods such as TLS, TTLS, PEAP and EAP-FAST. RADIUS server authenticates the users based on their credentials (username and password), digital certificates or both. + +**{IDF_TARGET_NAME} supports WiFi Enterprise only in station mode.** + +{IDF_TARGET_NAME} Supports **WPA2-Enterprise** and **WPA3-Enterprise**. WPA3-Enterprise builds upon the foundation of WPA2-Enterprise with the additional requirement of using Protected Management Frames (PMF) and server certificate validation on all WPA3 connections. **WPA3-Enterprise also offers an addition secure mode using 192-bit minimum-strength security protocols and cryptographic tools to better protect sensitive data.** The 192-bit security mode offered by WPA3-Enterprise ensures the right combination of cryptographic tools are used and sets a consistent baseline of security within a WPA3 network. WPA3-Enterprise 192-bit mode is only supported by modules having :ref:`CONFIG_ESP_WIFI_GMAC_SUPPORT` :ref:`CONFIG_ESP_WIFI_GMAC_SUPPORT` support. Enable :ref:`CONFIG_WPA_SUITE_B_192` flag to support WPA3-Enterprise with 192-bit mode. + +{IDF_TARGET_NAME} supports the following EAP methods: + - EAP-TLS: This is a certificate-based method and only requires SSID and EAP-IDF. + - PEAP: This is a Protected EAP method. Username and password are mandatory. + - EAP-TTLS: This is a credential-based method. Only server authentication is mandatory while user authentication is optional. Username and Password are mandatory. It supports different Phase2 methods, such as: + - PAP: Password Authentication Protocol. + - CHAP: Challenge Handshake Authentication Protocol. + - MSCHAP and MSCHAP-V2. + - EAP-FAST: This is an authentication method based on Protected Access Credentials (PAC) which also uses identity and password. + +Example :example:`wifi/wifi_enterprise` demonstrates all the supported WiFi Enterprise methods except EAP-FAST. Please refer :example:`wifi/wifi_eap_fast` for EAP-FAST example. EAP method can be selected from the Example Configuration menu in ``idf.py menuconfig``. Refer to :idf_file:`examples/wifi/wifi_enterprise/README.md` for information on how to generate certificates and run the example. WPA3-Personal ------------- @@ -83,14 +69,20 @@ Wi-Fi Protected Access-3 (WPA3) is a set of enhancements to Wi-Fi access securit - Mandates Protected Management Frames (PMF), which provides protection for unicast and multicast robust management frames which include Disassoc and Deauth frames. This means that the attacker cannot disrupt an established WPA3 session by sending forged Assoc frames to the AP or Deauth/Disassoc frames to the Station. - Provides forward secrecy, which means the captured data cannot be decrypted even if password is compromised after data transmission. +**{IDF_TARGET_NAME} station also supports following additional Wi-Fi CERTIFIED WPA3™ features.** + + - **Transition Disable** : WPA3 defines transition modes for client devices so that they can connect to a network even when some of the APs in that network do not support the strongest security mode. Client device implementations typically configure network profiles in a transition mode by default. However, such a client device could be subject to an active downgrade attack in which the attacker causes the client device to use a lower security mode in order to exploit a vulnerability with that mode. WPA3 has introduced the Transition Disable feature to mitigate such attacks, by enabling client devices to change from a transition mode to an “only” mode when connecting to a network, once that network indicates it fully supports the higher security mode. Enable :cpp:type:`transition_disable` in :cpp:type:`wifi_sta_config_t` to enable this feature for {IDF_TARGET_NAME} station. + + - **SAE PWE Methods**: {IDF_TARGET_NAME} station supports SAE Password Element derivation method `Hunting And Pecking` and `Hash to Element (H2E)`. H2E is computationally efficient as it uses less iterations than Hunt and Peck, also it mitigates side channel attacks. These can be configured using parameter :cpp:type:`sae_pwe_h2e` from :cpp:type:`wifi_sta_config_t` for station. Hunt and peck, H2E both can be enabled by using :cpp:enumerator:`WPA3_SAE_PWE_BOTH` configuration. + Please refer to `Security `_ section of Wi-Fi Alliance's official website for further details. -Setting up WPA3 with {IDF_TARGET_NAME} -++++++++++++++++++++++++++++++++++++++ +Setting up WPA3 Personal with {IDF_TARGET_NAME} ++++++++++++++++++++++++++++++++++++++++++++++++ -In IDF Menuconfig under Wi-Fi component, a config option "Enable WPA3-Personal" is provided to Enable/Disable WPA3. By default it is kept enabled, if disabled {IDF_TARGET_NAME} will not be able to establish a WPA3 connection. Currently, WPA3 is supported only in the Station mode. Additionally, since PMF is mandated by WPA3 protocol, PMF Mode should be set to either Optional or Required while setting WiFi config. +A config option :ref:`CONFIG_ESP32_WIFI_ENABLE_WPA3_SAE` is provided to Enable/Disable WPA3 for station. By default it is kept enabled, if disabled {IDF_TARGET_NAME} will not be able to establish a WPA3 connection. Additionally, since PMF is mandated by WPA3 protocol, PMF Mode Optional is set by default for station. PMF Required can be configured using WiFi config. Refer to `Protected Management Frames (PMF)`_ on how to set this mode. -After these settings are done, Station is ready to use WPA3-Personal. Application developers need not worry about the underlying security mode of the AP. WPA3-Personal is now the highest supported protocol in terms of security, so it will be automatically selected for the connection whenever available. For example, if an AP is configured to be in WPA3 Transition Mode, where it will advertise as both WPA2 and WPA3 capable, Station will choose WPA3 for the connection with above settings. -Note that Wi-Fi stack size requirement will increase 3kB when WPA3 is used. +After configuring all required settings for WPA3-Personal station, application developers need not worry about the underlying security mode of the AP. WPA3-Personal is now the highest supported protocol in terms of security, so it will be automatically selected for the connection whenever available. For example, if an AP is configured to be in WPA3 Transition Mode, where it will advertise as both WPA2 and WPA3 capable, Station will choose WPA3 for the connection with above settings. +Note that Wi-Fi stack size requirement will increase 3kB when "Enable WPA3-Personal" is used. diff --git a/docs/en/api-guides/wifi.rst b/docs/en/api-guides/wifi.rst index 68adab68308..756d0953467 100644 --- a/docs/en/api-guides/wifi.rst +++ b/docs/en/api-guides/wifi.rst @@ -1831,7 +1831,7 @@ Theoretically, if the side-effects the API imposes on the Wi-Fi driver or other The recommendations above are only for avoiding side-effects and can be ignored when there are good reasons. * - Have Wi-Fi connection - - When the Wi-Fi connection is already set up, and the sequence is controlled by the application, the latter may impact the sequence control of the Wi-Fi connection as a whole. So, the en_sys_seq need to be true, otherwise ESP_ERR_WIFI_ARG is returned. + - When the Wi-Fi connection is already set up, and the sequence is controlled by the application, the latter may impact the sequence control of the Wi-Fi connection as a whole. So, the ``en_sys_seq`` need to be true, otherwise ``ESP_ERR_INVALID_ARG`` is returned. The MAC-address recommendations in the “No Wi-Fi connection” scenario also apply to this scenario. @@ -1843,7 +1843,7 @@ Theoretically, if the side-effects the API imposes on the Wi-Fi driver or other - If the packet is sent from station to AP or from AP to station, the Power Management, More Data, and Re-Transmission bits should be 0. Otherwise, the packet will be discarded by Wi-Fi driver. - ESP_ERR_WIFI_ARG is returned if any check fails. + ``ESP_ERR_INVALID_ARG`` is returned if any check fails. Wi-Fi Sniffer Mode diff --git a/docs/zh_CN/api-guides/wifi.rst b/docs/zh_CN/api-guides/wifi.rst index 0203ba36c4d..1190c8409ed 100644 --- a/docs/zh_CN/api-guides/wifi.rst +++ b/docs/zh_CN/api-guides/wifi.rst @@ -1749,7 +1749,7 @@ Wi-Fi 80211 数据包发送 | | 上述建议仅供避免副作用，在有充分理由的情况下可以忽略。 | +---------------+--------------------------------------------------------------------------------------------+ | 有 Wi-Fi 连接 | 当 Wi-Fi 已连接，且序列由应用程序控制，应用程序可能会影响整个 Wi-Fi | -| | 连接的序列控制。 因此，en_sys_seq 要为 true，否则将返回 ESP_ERR_WIFI_ARG。 | +| | 连接的序列控制。 因此，en_sys_seq 要为 true，否则将返回 ESP_ERR_INVALID_ARG。 | | | | | | “无 Wi-Fi 连接” 情况下的 MAC 地址建议也适用于此情况。如果 Wi-Fi | | | 模式是 Station 模式，MAC 的地址 1 是 station 所连 AP 的 MAC，地址 | @@ -1774,7 +1774,7 @@ Wi-Fi 80211 数据包发送 | | | | | Data 和 Re-Transmission 位应该为 0，否则，Wi-Fi 驱动程序不接受该数据包。 | | | | -| | 如果任何检查失败，将返回 ESP_ERR_WIFI_ARG。 | +| | 如果任何检查失败，将返回 ESP_ERR_INVALID_ARG。 | +---------------+--------------------------------------------------------------------------------------------+ Wi-Fi Sniffer 模式 From a319ccb55277072de224272ee123c7f918be3b47 Mon Sep 17 00:00:00 2001 From: Shreyas Sheth Date: Wed, 6 Sep 2023 12:58:33 +0530 Subject: [PATCH 2/2] fix(wifi): Fix crash occuring when station SAE group is not set to SECP256R1 --- components/esp_wifi/Kconfig | 2 +- components/esp_wifi/lib | 2 +- components/wpa_supplicant/Kconfig | 1 + components/wpa_supplicant/src/common/sae.c | 1 - docs/zh_CN/api-guides/wifi.rst | 4 ++-- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/components/esp_wifi/Kconfig b/components/esp_wifi/Kconfig index 2d7b8321ca3..d5ae7c6a8cc 100644 --- a/components/esp_wifi/Kconfig +++ b/components/esp_wifi/Kconfig @@ -244,7 +244,7 @@ menu "Wi-Fi" config ESP32_WIFI_ENABLE_WPA3_SAE bool "Enable WPA3-Personal" default y - depends on WPA_MBEDTLS_CRYPTO + select WPA_MBEDTLS_CRYPTO help Select this option to allow the device to establish a WPA3-Personal connection with eligible AP's. PMF (Protected Management Frames) is a prerequisite feature for a WPA3 connection, it needs to be diff --git a/components/esp_wifi/lib b/components/esp_wifi/lib index 6fd120a997d..ffefe60c4ed 160000 --- a/components/esp_wifi/lib +++ b/components/esp_wifi/lib @@ -1 +1 @@ -Subproject commit 6fd120a997d581bbee290b1c6732c93869feef99 +Subproject commit ffefe60c4ed6babde69f37456ddf1ea39e395c0a diff --git a/components/wpa_supplicant/Kconfig b/components/wpa_supplicant/Kconfig index 1536a508cfa..85de704e417 100644 --- a/components/wpa_supplicant/Kconfig +++ b/components/wpa_supplicant/Kconfig @@ -8,6 +8,7 @@ menu "Supplicant" select MBEDTLS_ECDH_C select MBEDTLS_ECDSA_C select MBEDTLS_TLS_ENABLED + select MBEDTLS_ECP_DP_SECP256R1_ENABLED help Select this option to use MbedTLS crypto APIs which utilize hardware acceleration. diff --git a/components/wpa_supplicant/src/common/sae.c b/components/wpa_supplicant/src/common/sae.c index 3d04995327f..6945606fbec 100644 --- a/components/wpa_supplicant/src/common/sae.c +++ b/components/wpa_supplicant/src/common/sae.c @@ -77,7 +77,6 @@ int sae_set_group(struct sae_data *sae, int group) /* Unsupported group */ wpa_printf(MSG_DEBUG, "SAE: Group %d not supported by the crypto library", group); - os_free(tmp); return ESP_FAIL; } diff --git a/docs/zh_CN/api-guides/wifi.rst b/docs/zh_CN/api-guides/wifi.rst index 1190c8409ed..f62634ae198 100644 --- a/docs/zh_CN/api-guides/wifi.rst +++ b/docs/zh_CN/api-guides/wifi.rst @@ -1749,7 +1749,7 @@ Wi-Fi 80211 数据包发送 | | 上述建议仅供避免副作用，在有充分理由的情况下可以忽略。 | +---------------+--------------------------------------------------------------------------------------------+ | 有 Wi-Fi 连接 | 当 Wi-Fi 已连接，且序列由应用程序控制，应用程序可能会影响整个 Wi-Fi | -| | 连接的序列控制。 因此，en_sys_seq 要为 true，否则将返回 ESP_ERR_INVALID_ARG。 | +| | 连接的序列控制。 因此，en_sys_seq 要为 true，否则将返回 ESP_ERR_INVALID_ARG。 | | | | | | “无 Wi-Fi 连接” 情况下的 MAC 地址建议也适用于此情况。如果 Wi-Fi | | | 模式是 Station 模式，MAC 的地址 1 是 station 所连 AP 的 MAC，地址 | @@ -1774,7 +1774,7 @@ Wi-Fi 80211 数据包发送 | | | | | Data 和 Re-Transmission 位应该为 0，否则，Wi-Fi 驱动程序不接受该数据包。 | | | | -| | 如果任何检查失败，将返回 ESP_ERR_INVALID_ARG。 | +| | 如果任何检查失败，将返回 ESP_ERR_INVALID_ARG。 | +---------------+--------------------------------------------------------------------------------------------+ Wi-Fi Sniffer 模式