mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
docs(wifi): Update wifi and wifi security documentation
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
This commit is contained in:
Shreyas Sheth
muhaidong
parent
554e6880bc
commit
05915fee6e
@ -1,5 +1,5 @@
|
||||
/*
|
||||
* SPDX-FileCopyrightText: 2017-2022 Espressif Systems (Shanghai) CO LTD
|
||||
* SPDX-FileCopyrightText: 2017-2023 Espressif Systems (Shanghai) CO LTD
|
||||
*
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
@ -1400,7 +1400,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);
|
||||
@ -1417,7 +1417,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);
|
||||
@ -1506,7 +1506,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);
|
||||
|
||||
|
||||
@ -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);
|
||||
|
||||
|
||||
@ -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
|
||||
@ -439,7 +439,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);
|
||||
|
||||
|
||||
@ -350,9 +350,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 device and the AP is established.
|
||||
* If device is scanning and connecting at the same time, it will abort scanning and return a warning message and error
|
||||
* number ESP_ERR_WIFI_STATE.
|
||||
* If you want to do reconnection after device 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 device 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
|
||||
@ -407,7 +407,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
|
||||
*
|
||||
@ -792,7 +795,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);
|
||||
|
||||
@ -939,7 +942,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);
|
||||
|
||||
@ -952,7 +955,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);
|
||||
|
||||
@ -981,7 +984,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);
|
||||
|
||||
@ -1001,7 +1004,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
|
||||
@ -1073,7 +1076,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);
|
||||
|
||||
@ -1085,7 +1088,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);
|
||||
|
||||
@ -1098,7 +1101,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);
|
||||
|
||||
@ -1110,7 +1113,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);
|
||||
|
||||
@ -1143,7 +1146,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);
|
||||
|
||||
@ -1157,7 +1160,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);
|
||||
|
||||
@ -1173,16 +1176,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);
|
||||
|
||||
@ -1347,8 +1351,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
|
||||
*/
|
||||
|
||||
@ -308,7 +308,7 @@ typedef struct {
|
||||
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_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 */
|
||||
|
||||
@ -1 +1 @@
|
||||
Subproject commit 832650b7125b6518d83c35f359b66fba9459ced7
|
||||
Subproject commit e4c92778b87d8246a4dc10f59520e88b340ab18e
|
||||
@ -33,7 +33,7 @@ extern "C" {
|
||||
* @brief Enable wpa2 enterprise authentication.
|
||||
*
|
||||
* @attention 1. wpa2 enterprise authentication can only be used when station mode is enabled.
|
||||
* @attention 2. wpa2 enterprise authentication can only support TLS, PEAP-MSCHAPv2 and TTLS-MSCHAPv2 method.
|
||||
* @attention 2. wpa2 enterprise authentication supports EAP-FAST, TLS, PEAP, TTLS(EAP, MSCHAPv2, MSCHAP, PAP, CHAP) methods.
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK: succeed.
|
||||
@ -45,7 +45,7 @@ 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 station mode is enabled.
|
||||
* @attention 2. wpa2 enterprise authentication can only support TLS, PEAP-MSCHAPv2 and TTLS-MSCHAPv2 method.
|
||||
* @attention 2. wpa2 enterprise authentication supports EAP-FAST, TLS, PEAP, TTLS(EAP, MSCHAPv2, MSCHAP, PAP, CHAP) methods.
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK: succeed.
|
||||
|
||||
@ -5,8 +5,9 @@ Wi-Fi Security
|
||||
-----------------------------------------
|
||||
- Support for Protected Management Frames (PMF)
|
||||
- Support for WPA3-Personal
|
||||
- Support for Opportunistic Wireless Encryption
|
||||
|
||||
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 and Enhanced Open based on Opportunistic Wireless Encryption. WPA3 provides better privacy and robustness against known attacks on traditional modes. Enhanced Open enhances security and privacy of users connecting to open (public) Wireless Network without authentication.
|
||||
|
||||
Protected Management Frames (PMF)
|
||||
---------------------------------
|
||||
@ -15,13 +16,7 @@ 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.
|
||||
|
||||
@ -30,24 +25,6 @@ There are 3 types of PMF configuration modes on both station and AP side -
|
||||
- PMF Required
|
||||
- PMF Disabled
|
||||
|
||||
Depending on PMF configurations on Station and AP side, the resulting connection will behave differently. The table below 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
|
||||
+++++++++++
|
||||
|
||||
@ -57,6 +34,29 @@ API & Usage
|
||||
|
||||
``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 :c:macro:`SOC_WIFI_GCMP_SUPPORT` support. Enable :ref:`CONFIG_ESP_WIFI_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. Currently, :ref:`CONFIG_ESP_WIFI_MBEDTLS_TLS_CLIENT` flag should be disabled to use this feature.
|
||||
|
||||
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
|
||||
-------------
|
||||
|
||||
@ -70,17 +70,40 @@ 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 PUBLIC-KEY (PK)** : As the password at small public networks is shared with multiple users it may be relatively easy for an attacker to find out the password, which is sufficient to launch an evil twin attack. Such attacks are prevented by an extension to WPA3-Personal called SAE-PK. The SAE-PK authentication exchange is very similar to the regular SAE exchange, with the addition of a digital signature sent by the AP to the client device. The client device validates the public key asserted by the AP based on the password fingerprint, and verifies the signature using the public key. So even if the attacker knows the password, it does not know the private key to generate a valid signature, and therefore the client device is protected against an evil twin attack. Enable :ref:`CONFIG_ESP_WIFI_ENABLE_SAE_PK` and :cpp:type:`sae_pk_mode` in :cpp:type:`wifi_sta_config_t` to add support of SAE PK for {IDF_TARGET_NAME} station.
|
||||
|
||||
- **SAE PWE Methods**: {IDF_TARGET_NAME} station as well as softAP 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` and :cpp:type:`wifi_ap_config_t` for station and softAP respectively. Hunt and peck, H2E both can be enabled by using :cpp:enumerator:`WPA3_SAE_PWE_BOTH` configuration.
|
||||
|
||||
Please refer to `Security <https://www.wi-fi.org/discover-wi-fi/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 for station. By default it is kept enabled, if disabled {IDF_TARGET_NAME} will not be able to establish a WPA3 connection. Also under WI-FI component a config option "ESP_WIFI_SOFTAP_SAE_SUPPORT" is provided to Enable/Disable WPA3 for softAP. Additionally, since PMF is mandated by WPA3 protocol, PMF Mode Optional is set by default for station and softAP. PMF Required can be configured using WiFi config. For WPA3 softAP, PMF required is mandatory and will be configured and stored in NVS implicitly if not specified by user.
|
||||
A config option :ref:`CONFIG_ESP_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. Also under WI-FI component a config option :ref:`CONFIG_ESP_WIFI_SOFTAP_SAE_SUPPORT` is provided to Enable/Disable WPA3 for softAP. Additionally, since PMF is mandated by WPA3 protocol, PMF Mode Optional is set by default for station and softAP. PMF Required can be configured using WiFi config. For WPA3 softAP, PMF required is mandatory and will be configured and stored in NVS implicitly if not specified by user.
|
||||
|
||||
Refer to `Protected Management Frames (PMF)`_ on how to set this mode.
|
||||
|
||||
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.
|
||||
|
||||
After configuring all required setting for WPA3-Personal softAP, application developers have to set ``WIFI_AUTH_WPA3_PSK`` as WiFi config authmode to start AP in softAP. SoftAP can be also configured to use ``WIFI_AUTH_WPA2_WPA3_PSK`` mixed mode.
|
||||
Note that flash size will be increased by 6kB after enabling "ESP_WIFI_SOFTAP_SAE_SUPPORT".
|
||||
After configuring all required setting for WPA3-Personal softAP, application developers have to set ``WIFI_AUTH_WPA3_PSK`` for `authmode` in :cpp:type:`wifi_ap_config_t` to start AP in WPA3 security. SoftAP can be also configured to use ``WIFI_AUTH_WPA2_WPA3_PSK`` mixed mode.
|
||||
Note that binary size will be increased by ~6.5 kilobytes after enabling ":ref:`CONFIG_ESP_WIFI_SOFTAP_SAE_SUPPORT`.
|
||||
|
||||
Wi-Fi Enhanced Open™
|
||||
--------------------
|
||||
|
||||
Introduction
|
||||
++++++++++++
|
||||
|
||||
Enhanced open is used for providing security and privacy to users connecting to open (public) wireless networks, particularly in scenarios where user authentication is not desired or distribution of credentials impractical. Each user is provided with unique individual encryption keys that protect data exchange between a user device and the Wi-Fi network. Protected Management Frames further protects management traffic between the access point and user device. Enhanced Open is based on Opportunistic Wireless Encryption (OWE) standard. OWE Transition Mode enables a seamless transition from Open unencrypted WLANs to OWE WLANs without adversely impacting the end user experience.
|
||||
|
||||
**{IDF_TARGET_NAME} supports Wi‑Fi Enhanced Open™ only in station mode.**
|
||||
|
||||
Setting up OWE with {IDF_TARGET_NAME}
|
||||
++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
A config option :ref:`CONFIG_ESP_WIFI_ENABLE_WPA3_OWE_STA` and configuration parameter :cpp:type:`owe_enabled` in :cpp:type:`wifi_sta_config_t` is provided to enable OWE support for station. To use OWE transition mode, along with the config provided above, `authmode` from :cpp:type:`wifi_scan_threshold_t` should be set to `WIFI_AUTH_OPEN`.
|
||||
|
||||
@ -1654,7 +1654,6 @@ Wi-Fi Vendor IE Configuration
|
||||
|
||||
By default, all Wi-Fi management frames are processed by the Wi-Fi driver, and the application can ignore them. However, some applications may have to handle the beacon, probe request, probe response, and other management frames. For example, if you insert some vendor-specific IE into the management frames, it is only the management frames which contain this vendor-specific IE that will be processed. In {IDF_TARGET_NAME}, :cpp:func:`esp_wifi_set_vendor_ie()` and :cpp:func:`esp_wifi_set_vendor_ie_cb()` are responsible for this kind of tasks.
|
||||
|
||||
|
||||
Wi-Fi Easy Connect™ (DPP)
|
||||
--------------------------
|
||||
|
||||
@ -1708,6 +1707,15 @@ Current implementation of 802.11k includes support for beacon measurement report
|
||||
|
||||
Refer ESP-IDF example :idf_file:`examples/wifi/roaming/README.md` to set up and use these APIs. Example code only demonstrates how these APIs can be used, and the application should define its own algorithm and cases as required.
|
||||
|
||||
Fast BSS Transition
|
||||
---------------------------
|
||||
Fast BSS transition (802.11R FT), is a standard to permit continuous connectivity aboard wireless devices in motion, with fast and secure client transitions from one Basic Service Set (abbreviated BSS, and also known as a base station or more colloquially, an access point) to another performed in a nearly seamless manner **avoiding 802.1i 4 way handshake** . 802.11R specifies transitions between access points by redefining the security key negotiation protocol, allowing both the negotiation and requests for wireless resources to occur in parallel. The key derived from the server to be cached in the wireless network, so that a reasonable number of future connections can be based on the cached key, avoiding the 802.1X process
|
||||
|
||||
|
||||
{IDF_TARGET_NAME} station supports FT for WPA2-PSK networks. Do note that {IDF_TARGET_NAME} station only support FT over the air protocol only.
|
||||
|
||||
A config option :ref:`CONFIG_ESP_WIFI_11R_SUPPORT` and configuration parameter :cpp:type:`ft_enabled` in :cpp:type:`wifi_sta_config_t` is provided to enable 802.11R support for station. Refer ESP-IDF example :idf_file:`examples/wifi/roaming/README.md` for further details.
|
||||
|
||||
.. only:: SOC_WIFI_FTM_SUPPORT
|
||||
|
||||
Wi-Fi Location
|
||||
@ -2111,7 +2119,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.
|
||||
|
||||
@ -2123,7 +2131,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
|
||||
|
||||
@ -2068,7 +2068,7 @@ Wi-Fi 80211 数据包发送
|
||||
上述建议仅供避免副作用，在有充分理由的情况下可以忽略。
|
||||
|
||||
* - 有 Wi-Fi 连接
|
||||
- 当 Wi-Fi 已连接，且序列由应用程序控制，应用程序可能会影响整个 Wi-Fi 连接的序列控制。 因此，en_sys_seq 要为 true，否则将返回 ``ESP_ERR_WIFI_ARG``。
|
||||
- 当 Wi-Fi 已连接，且序列由应用程序控制，应用程序可能会影响整个 Wi-Fi 连接的序列控制。 因此，en_sys_seq 要为 true，否则将返回 ``ESP_ERR_INVALID_ARG``。
|
||||
|
||||
“无 Wi-Fi 连接”情况下的 MAC 地址建议也适用于此情况。
|
||||
|
||||
@ -2080,7 +2080,7 @@ Wi-Fi 80211 数据包发送
|
||||
|
||||
- 如果数据包是从 station 发送到 AP，或从 AP 到 station，Power Management、More Data 和 Re-Transmission 位应该为 0，否则，Wi-Fi 驱动程序不接受该数据包。
|
||||
|
||||
如果任何检查失败，将返回 ``ESP_ERR_WIFI_ARG``。
|
||||
如果任何检查失败，将返回 ``ESP_ERR_INVALID_ARG``。
|
||||
|
||||
|
||||
Wi-Fi Sniffer 模式
|
||||
|
||||
Loading…
Reference in New Issue
Block a user