mirror of
https://github.com/espressif/esp-idf.git
synced 2024-09-20 00:36:01 -04:00
docs: Separate Doc on WiFi security, added DPP Doc
1. Add new Doc on WiFi security 2. Add DPP related Doc under WiFi 3. Add Supplicant public headers in Doxyfile
This commit is contained in:
Nachiket Kukade
parent
0f0bd29f8f
commit
f38b18f046
@ -34,6 +34,7 @@ INPUT = \
|
||||
$(IDF_PATH)/components/esp_wifi/include/esp_now.h \
|
||||
$(IDF_PATH)/components/esp_wifi/include/esp_wifi_default.h \
|
||||
$(IDF_PATH)/components/esp_wifi/include/esp_mesh.h \
|
||||
$(IDF_PATH)/components/wpa_supplicant/esp_supplicant/include/esp_dpp.h \
|
||||
$(IDF_PATH)/components/esp_event/include/esp_event.h \
|
||||
$(IDF_PATH)/components/esp_event/include/esp_event_base.h \
|
||||
$(IDF_PATH)/components/esp_event/include/esp_event_legacy.h \
|
||||
|
||||
@ -44,4 +44,5 @@ API Guides
|
||||
:esp32: Unit Testing (Legacy GNU Make) <unit-tests-legacy>
|
||||
:SOC_USB_OTG_SUPPORTED: USB OTG Console <usb-otg-console>
|
||||
:SOC_USB_SERIAL_JTAG_SUPPORTED: USB Serial/JTAG Controller Console <usb-serial-jtag-console>
|
||||
WiFi Driver <wifi>
|
||||
Wi-Fi Driver <wifi>
|
||||
Wi-Fi Security <wifi-security>
|
||||
|
||||
95
docs/en/api-guides/wifi-security.rst
Normal file
95
docs/en/api-guides/wifi-security.rst
Normal file
@ -0,0 +1,95 @@
|
||||
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.
|
||||
|
||||
API & Usage
|
||||
+++++++++++
|
||||
|
||||
: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 -
|
||||
|
||||
+--------------+------------------------+---------------------------+
|
||||
| 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 |
|
||||
+--------------+------------------------+---------------------------+
|
||||
|
||||
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.
|
||||
|
||||
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. 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.
|
||||
|
||||
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.
|
||||
@ -7,7 +7,7 @@ Wi-Fi Driver
|
||||
------------------------------------
|
||||
- Support Station-only mode, AP-only mode, Station/AP-coexistence mode
|
||||
- Support IEEE 802.11B, IEEE 802.11G, IEEE 802.11N and APIs to configure the protocol mode
|
||||
- Support WPA/WPA2/WPA2-Enterprise and WPS
|
||||
- Support WPA/WPA2/WPA3/WPA2-Enterprise and WPS
|
||||
- Support AMPDU, HT40, QoS and other key features
|
||||
- Support Modem-sleep
|
||||
- Support an Espressif-specific protocol which, in turn, supports up to **1 km** of data traffic
|
||||
@ -1403,41 +1403,12 @@ Wi-Fi Vendor IE Configuration
|
||||
|
||||
By default, all Wi-Fi management frames are processed by the Wi-Fi driver, and the application does not need to care about them. Some applications, however, 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 Security
|
||||
-------------------------------
|
||||
|
||||
In addition to traditional security methods (WEP/WPA-TKIP/WPA2-CCMP), {IDF_TARGET_NAME} Wi-Fi now 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 in traditional modes.
|
||||
|
||||
Protected Management Frames (PMF)
|
||||
++++++++++++++++++++++++++++++++++
|
||||
|
||||
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 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.
|
||||
|
||||
{IDF_TARGET_NAME} supports the following three modes of operation with respect to PMF.
|
||||
|
||||
- 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.
|
||||
|
||||
: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.
|
||||
|
||||
|
||||
WPA3-Personal
|
||||
+++++++++++++++++++++++++++++++++
|
||||
|
||||
Wi-Fi Protected Access-3 (WPA3) is a set of enhancements to Wi-Fi access security intended to replace the current WPA2 standard. In order to provide more robust authentication, 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. WPA3 also 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.
|
||||
|
||||
In order to enable WPA3-Personal, "Enable WPA3-Personal" should be selected in menuconfig. If enabled, {IDF_TARGET_NAME} uses SAE for authentication if supported by the AP. Since PMF is a mandatory requirement for WPA3, PMF capability should be at least set to "PMF capable, but not required" for {IDF_TARGET_NAME} to use WPA3 mode. Application developers need not worry about the underlying security mode as highest available is chosen from security standpoint. Note that Wi-Fi stack size requirement will increase approximately by 3k when WPA3 is used. Currently, WPA3 is supported only in Station mode.
|
||||
Wi-Fi Easy Connect™ (DPP)
|
||||
--------------------------
|
||||
|
||||
Wi-Fi Easy Connect\ :sup:`TM` (or Device Provisioning Protocol) is a secure and standardized provisioning protocol for configuration of Wi-Fi Devices.
|
||||
More information can be found on the API reference page :doc:`esp_dpp <../api-reference/network/esp_dpp>`.
|
||||
|
||||
WPA2-Enterprise
|
||||
+++++++++++++++++++++++++++++++++
|
||||
|
||||
26
docs/en/api-reference/network/esp_dpp.rst
Normal file
26
docs/en/api-reference/network/esp_dpp.rst
Normal file
@ -0,0 +1,26 @@
|
||||
Wi-Fi Easy Connect\ :sup:`TM` (DPP)
|
||||
===================================
|
||||
|
||||
Wi-Fi Easy Connect\ :sup:`TM`, also known as Device Provisioning Protocol (DPP) or Easy Connect, is a provisioning protocol certified by Wi-Fi Alliance. It is a secure and standardized provisioning protocol for configuration of Wi-Fi Devices. With Easy Connect adding a new device to a network is as simple as scanning a QR Code. This reduces complexity and enhances user experience while onboarding devices without UI like Smart Home and IoT products. Unlike old protocols like WiFi Protected Setup (WPS), Wi-Fi Easy Connect incorporates strong encryption through public key cryptography to ensure networks remain secure as new devices are added.
|
||||
Easy Connect brings many benefits in the User Experience:
|
||||
|
||||
- Simple and intuitive to use; no lengthy instructions to follow for new device setup
|
||||
- No need to remember and enter passwords into the device being provisioned
|
||||
- Works with electronic or printed QR codes, or human-readable strings
|
||||
- Supports both WPA2 and WPA3 networks
|
||||
|
||||
Please refer to Wi-Fi Alliance's official page on `Easy Connect <https://www.wi-fi.org/discover-wi-fi/wi-fi-easy-connect>`_ for more information.
|
||||
|
||||
{IDF_TARGET_NAME} supports Enrollee mode of Easy Connect with QR Code as the provisioning method. A display is required to display this QR Code. Users can scan this QR Code using their capable device and provision the {IDF_TARGET_NAME} to their Wi-Fi network. The provisioning device needs to be connected to the AP which need not support Wi-Fi Easy Connect™.
|
||||
Easy Connect is still an evolving protocol. Of known platforms that support the QR Code method are some Android smartphones with Android 10 or higher. To use Easy Connect no additional App needs to be installed on the supported smartphone.
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
Example on how to provision {IDF_TARGET_NAME} using a supported smartphone: :example:`wifi/wifi_easy_connect/dpp-enrollee`.
|
||||
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_dpp.inc
|
||||
@ -13,6 +13,7 @@ Wi-Fi
|
||||
SmartConfig <esp_smartconfig>
|
||||
ESP-NOW <esp_now>
|
||||
ESP-WIFI-MESH <esp-wifi-mesh>
|
||||
EasyConnect <esp_dpp>
|
||||
|
||||
Code examples for the Wi-Fi API are provided in the :example:`wifi` directory of ESP-IDF examples.
|
||||
|
||||
|
||||
@ -18,3 +18,10 @@ Code examples for above API are provided in the :example:`provisioning` director
|
||||
SmartConfig <../network/esp_smartconfig>
|
||||
|
||||
Code example for above API is provided in :example:`wifi/smart_config`
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
EasyConnect <../network/esp_dpp>
|
||||
|
||||
Code example for above API is provided in :example:`wifi/wifi_easy_connect/dpp-enrollee`
|
||||
|
||||
@ -45,3 +45,4 @@ API 指南
|
||||
:SOC_USB_OTG_SUPPORTED: USB 控制台 <usb-otg-console>
|
||||
:SOC_USB_SERIAL_JTAG_SUPPORTED: USB Serial/JTAG Controller Console <usb-serial-jtag-console>
|
||||
Wi-Fi 驱动 <wifi>
|
||||
Wi-Fi Security <wifi-security>
|
||||
|
||||
1
docs/zh_CN/api-guides/wifi-security.rst
Normal file
1
docs/zh_CN/api-guides/wifi-security.rst
Normal file
@ -0,0 +1 @@
|
||||
.. include:: ../../en/api-guides/wifi-security.rst
|
||||
1
docs/zh_CN/api-reference/network/esp_dpp.rst
Normal file
1
docs/zh_CN/api-reference/network/esp_dpp.rst
Normal file
@ -0,0 +1 @@
|
||||
.. include:: ../../../en/api-reference/network/esp_dpp.rst
|
||||
@ -13,6 +13,7 @@ Wi-Fi
|
||||
Smart Config <esp_smartconfig>
|
||||
ESP-NOW <esp_now>
|
||||
ESP-WIFI-MESH <esp-wifi-mesh>
|
||||
EasyConnect <esp_dpp>
|
||||
|
||||
本部分的 Wi-Fi API 示例代码存放在 ESP-IDF 示例项目的 :example:`wifi` 目录下。
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user