mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
888b909e79
1) Set NVS PMF required true if not specified by application when authmode is WPA3 2) Fix issue regarding cleanup of non associated sta_info 3) Fix implementation of sta lock to avoid concurrency issues 4) Fix softAP deinit crash when password is configured with max length
87 lines
6.9 KiB
ReStructuredText
87 lines
6.9 KiB
ReStructuredText
Wi-Fi Security
|
|
==============
|
|
|
|
{IDF_TARGET_NAME} Wi-Fi Security Features
|
|
-----------------------------------------
|
|
- 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.
|
|
|
|
Protected Management Frames (PMF)
|
|
---------------------------------
|
|
|
|
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.
|
|
|
|
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 -
|
|
- PMF Optional
|
|
- 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
|
|
+++++++++++
|
|
|
|
{IDF_TARGET_NAME} supports PMF in both Station and SoftAP mode. For both, the default mode is PMF Optional. 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 the device only connecting to a PMF enabled device and rejecting others. PMF optional can be disabled using :cpp:func:`esp_wifi_disable_pmf_config` API. If softAP is started in WPA3 or WPA2/WPA3 mixed mode trying to disable PMF will result in error.
|
|
|
|
.. 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
|
|
-------------
|
|
|
|
Introduction
|
|
++++++++++++
|
|
|
|
Wi-Fi Protected Access-3 (WPA3) is a set of enhancements to Wi-Fi access security intended to replace the current WPA2 standard. It includes new features and capabilities that offer significantly better protection against different types of attacks. It improves upon WPA2-Personal in following ways:
|
|
|
|
- WPA3 uses Simultaneous Authentication of Equals (SAE), which is password-authenticated key agreement method based on Diffie-Hellman key exchange. Unlike WPA2, the technology is resistant to offline-dictionary attack, where the attacker attempts to determine shared password based on captured 4-way handshake without any further network interaction.
|
|
- Disallows outdated protocols such as TKIP, which is susceptible to simple attacks like MIC key recovery attack.
|
|
- 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.
|
|
|
|
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}
|
|
++++++++++++++++++++++++++++++++++++++
|
|
|
|
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.
|
|
|
|
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".
|