diff --git a/components/wpa_supplicant/esp_supplicant/include/esp_eap_client.h b/components/wpa_supplicant/esp_supplicant/include/esp_eap_client.h index a6dc7d6aa5..1cbfac781e 100644 --- a/components/wpa_supplicant/esp_supplicant/include/esp_eap_client.h +++ b/components/wpa_supplicant/esp_supplicant/include/esp_eap_client.h @@ -13,18 +13,33 @@ extern "C" { #endif +/** + * @brief Enumeration of phase 2 authentication types for EAP-TTLS. + * + * This enumeration defines the supported phase 2 authentication methods + * that can be used in the EAP-TTLS (Extensible Authentication Protocol - + * Tunneled Transport Layer Security) protocol for the second authentication + * phase. + */ typedef enum { - ESP_EAP_TTLS_PHASE2_EAP, - ESP_EAP_TTLS_PHASE2_MSCHAPV2, - ESP_EAP_TTLS_PHASE2_MSCHAP, - ESP_EAP_TTLS_PHASE2_PAP, - ESP_EAP_TTLS_PHASE2_CHAP + ESP_EAP_TTLS_PHASE2_EAP, /**< EAP (Extensible Authentication Protocol) */ + ESP_EAP_TTLS_PHASE2_MSCHAPV2, /**< MS-CHAPv2 (Microsoft Challenge Handshake Authentication Protocol - Version 2) */ + ESP_EAP_TTLS_PHASE2_MSCHAP, /**< MS-CHAP (Microsoft Challenge Handshake Authentication Protocol) */ + ESP_EAP_TTLS_PHASE2_PAP, /**< PAP (Password Authentication Protocol) */ + ESP_EAP_TTLS_PHASE2_CHAP /**< CHAP (Challenge Handshake Authentication Protocol) */ } esp_eap_ttls_phase2_types; +/** + * @brief Configuration settings for EAP-FAST + * (Extensible Authentication Protocol - Flexible Authentication via Secure Tunneling). + * + * This structure defines the configuration options that can be used to customize the behavior of the + * EAP-FAST authentication protocol, specifically for Fast Provisioning and PAC (Protected Access Credential) handling. + */ typedef struct { - int fast_provisioning; /* Enables or disables Fast Provisioning in EAP-FAST */ - int fast_max_pac_list_len; /* Maximum length of the PAC (Protected Access Credential) list */ - bool fast_pac_format_binary; /* Set to true for binary format PAC, false for ASCII format PAC */ + int fast_provisioning; /**< Enable or disable Fast Provisioning in EAP-FAST (0 = disabled, 1 = enabled) */ + int fast_max_pac_list_len; /**< Maximum length of the PAC (Protected Access Credential) list */ + bool fast_pac_format_binary; /**< Set to true for binary format PAC, false for ASCII format PAC */ } esp_eap_fast_config; diff --git a/components/wpa_supplicant/esp_supplicant/include/esp_mbo.h b/components/wpa_supplicant/esp_supplicant/include/esp_mbo.h index 4292213943..4319ecc000 100644 --- a/components/wpa_supplicant/esp_supplicant/include/esp_mbo.h +++ b/components/wpa_supplicant/esp_supplicant/include/esp_mbo.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2021 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -13,39 +13,41 @@ extern "C" { #endif /** - * enum non_pref_chan_reason: Reason for non preference of channel - */ + * @brief Enumeration of reasons for a channel being non-preferred in a wireless network. + * + * This enumeration defines various reasons why a specific channel might be considered non-preferred + * in a wireless network configuration. + */ enum non_pref_chan_reason { - NON_PREF_CHAN_REASON_UNSPECIFIED = 0, - NON_PREF_CHAN_REASON_RSSI = 1, - NON_PREF_CHAN_REASON_EXT_INTERFERENCE = 2, - NON_PREF_CHAN_REASON_INT_INTERFERENCE = 3, + NON_PREF_CHAN_REASON_UNSPECIFIED = 0, /**< Unspecified reason for non-preference */ + NON_PREF_CHAN_REASON_RSSI = 1, /**< Non-preferred due to low RSSI (Received Signal Strength Indication) */ + NON_PREF_CHAN_REASON_EXT_INTERFERENCE = 2, /**< Non-preferred due to external interference */ + NON_PREF_CHAN_REASON_INT_INTERFERENCE = 3, /**< Non-preferred due to internal interference */ }; /** - * @brief Channel structure for non preferred channel - * - * @param reason: enum non_pref_chan_reason - * @param oper_class: operating class for the channel - * @param chan: channel number - * @param preference: channel preference - */ + * @brief Structure representing a non-preferred channel in a wireless network. + * + * This structure encapsulates information about a non-preferred channel + * including the reason for its non-preference, the operating class, channel number, and preference level. + */ struct non_pref_chan { - enum non_pref_chan_reason reason; - uint8_t oper_class; - uint8_t chan; - uint8_t preference; + enum non_pref_chan_reason reason; /**< Reason for the channel being non-preferred */ + uint8_t oper_class; /**< Operating class of the channel */ + uint8_t chan; /**< Channel number */ + uint8_t preference; /**< Preference level of the channel */ }; /** - * @brief Array structure for non preferred channel struct - * - * @param non_pref_chan_num: channel count - * @param chan: array of non_pref_chan type - */ + * @brief Structure representing a list of non-preferred channels in a wireless network. + * + * This structure encapsulates information about a list of non-preferred channels + * including the number of non-preferred channels and an array of structures + * representing individual non-preferred channels. + */ struct non_pref_chan_s { - size_t non_pref_chan_num; - struct non_pref_chan chan[]; + size_t non_pref_chan_num; /**< Number of non-preferred channels in the list */ + struct non_pref_chan chan[]; /**< Array of structures representing individual non-preferred channels */ }; /** diff --git a/components/wpa_supplicant/esp_supplicant/include/esp_wps.h b/components/wpa_supplicant/esp_supplicant/include/esp_wps.h index c9d60ecb8d..148bc81da7 100644 --- a/components/wpa_supplicant/esp_supplicant/include/esp_wps.h +++ b/components/wpa_supplicant/esp_supplicant/include/esp_wps.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2019-2021 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2019-2023 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -33,32 +33,60 @@ extern "C" { #define ESP_ERR_WIFI_WPS_TYPE (ESP_ERR_WIFI_BASE + 52) /*!< WPS type error */ #define ESP_ERR_WIFI_WPS_SM (ESP_ERR_WIFI_BASE + 53) /*!< WPS state machine is not initialized */ +/** + * @brief Enumeration of WPS (Wi-Fi Protected Setup) types. + */ typedef enum wps_type { - WPS_TYPE_DISABLE = 0, - WPS_TYPE_PBC, - WPS_TYPE_PIN, - WPS_TYPE_MAX, + WPS_TYPE_DISABLE = 0, /**< WPS is disabled */ + WPS_TYPE_PBC, /**< WPS Push Button Configuration method */ + WPS_TYPE_PIN, /**< WPS PIN (Personal Identification Number) method */ + WPS_TYPE_MAX /**< Maximum value for WPS type enumeration */ } wps_type_t; -#define WPS_MAX_MANUFACTURER_LEN 65 -#define WPS_MAX_MODEL_NUMBER_LEN 33 -#define WPS_MAX_MODEL_NAME_LEN 33 -#define WPS_MAX_DEVICE_NAME_LEN 33 +#define WPS_MAX_MANUFACTURER_LEN 65 /**< Maximum length of the manufacturer name in WPS information */ +#define WPS_MAX_MODEL_NUMBER_LEN 33 /**< Maximum length of the model number in WPS information */ +#define WPS_MAX_MODEL_NAME_LEN 33 /**< Maximum length of the model name in WPS information */ +#define WPS_MAX_DEVICE_NAME_LEN 33 /**< Maximum length of the device name in WPS information */ +/** + * @brief Structure representing WPS factory information for ESP device. + * + * This structure holds various strings representing factory information for a device, such as the manufacturer, + * model number, model name, and device name. Each string is a null-terminated character array. If any of the + * strings are empty, the default values are used. + */ typedef struct { - char manufacturer[WPS_MAX_MANUFACTURER_LEN]; /*!< Manufacturer, null-terminated string. The default manufcturer is used if the string is empty */ - char model_number[WPS_MAX_MODEL_NUMBER_LEN]; /*!< Model number, null-terminated string. The default model number is used if the string is empty */ - char model_name[WPS_MAX_MODEL_NAME_LEN]; /*!< Model name, null-terminated string. The default model name is used if the string is empty */ - char device_name[WPS_MAX_DEVICE_NAME_LEN]; /*!< Device name, null-terminated string. The default device name is used if the string is empty */ + char manufacturer[WPS_MAX_MANUFACTURER_LEN]; /*!< Manufacturer of the device. If empty, the default manufacturer is used. */ + char model_number[WPS_MAX_MODEL_NUMBER_LEN]; /*!< Model number of the device. If empty, the default model number is used. */ + char model_name[WPS_MAX_MODEL_NAME_LEN]; /*!< Model name of the device. If empty, the default model name is used. */ + char device_name[WPS_MAX_DEVICE_NAME_LEN]; /*!< Device name. If empty, the default device name is used. */ } wps_factory_information_t; -#define PIN_LEN 9 +#define PIN_LEN 9 /*!< The length of the WPS PIN (Personal Identification Number). */ +/** + * @brief Structure representing configuration settings for WPS (Wi-Fi Protected Setup). + * + * This structure encapsulates various configuration settings for WPS, including the WPS type (PBC or PIN), + * factory information that will be shown in the WPS Information Element (IE), and a PIN if the WPS type is + * set to PIN. + */ typedef struct { - wps_type_t wps_type; - wps_factory_information_t factory_info; - char pin[PIN_LEN]; + wps_type_t wps_type; /*!< The type of WPS to be used (PBC or PIN). */ + wps_factory_information_t factory_info; /*!< Factory information to be shown in the WPS Information Element (IE). Vendor can choose to display their own information. */ + char pin[PIN_LEN]; /*!< WPS PIN (Personal Identification Number) used when wps_type is set to WPS_TYPE_PIN. */ } esp_wps_config_t; +/** + * @def WPS_CONFIG_INIT_DEFAULT(type) + * @brief Initialize a default WPS configuration structure with specified WPS type. + * + * This macro initializes a `esp_wps_config_t` structure with default values for the specified WPS type. + * It sets the WPS type, factory information (including default manufacturer, model number, model name, and device name), + * and a default PIN value if applicable. + * + * @param type The WPS type to be used (PBC or PIN). + * @return An initialized `esp_wps_config_t` structure with the specified WPS type and default values. + */ #define WPS_CONFIG_INIT_DEFAULT(type) { \ .wps_type = type, \ .factory_info = { \ @@ -73,9 +101,7 @@ typedef struct { /** * @brief Enable Wi-Fi WPS function. * - * @attention WPS can only be used when station is enabled. - * - * @param wps_type_t wps_type : WPS type, so far only WPS_TYPE_PBC and WPS_TYPE_PIN is supported + * @param config : WPS config to be used in connection * * @return * - ESP_OK : succeed @@ -88,8 +114,6 @@ esp_err_t esp_wifi_wps_enable(const esp_wps_config_t *config); /** * @brief Disable Wi-Fi WPS function and release resource it taken. * - * @param null - * * @return * - ESP_OK : succeed * - ESP_ERR_WIFI_WPS_MODE : wifi is not in station mode or sniffer mode is on @@ -97,9 +121,9 @@ esp_err_t esp_wifi_wps_enable(const esp_wps_config_t *config); esp_err_t esp_wifi_wps_disable(void); /** - * @brief WPS starts to work. + * @brief Start WPS session. * - * @attention WPS can only be used when station is enabled. + * @attention WPS can only be used when station is enabled. WPS needs to be enabled first for using this API. * * @param timeout_ms : deprecated: This argument's value will have not effect in functionality of API. * The argument will be removed in future. @@ -120,7 +144,7 @@ esp_err_t esp_wifi_wps_start(int timeout_ms); * * @attention WPS can only be used when softAP is enabled. * - * @param esp_wps_config_t config: wps configuration to be used. + * @param config: wps configuration to be used. * * @return * - ESP_OK : succeed @@ -133,8 +157,6 @@ esp_err_t esp_wifi_ap_wps_enable(const esp_wps_config_t *config); /** * @brief Disable Wi-Fi SoftAP WPS function and release resource it taken. * - * @param null - * * @return * - ESP_OK : succeed * - ESP_ERR_WIFI_WPS_MODE : wifi is not in station mode or sniffer mode is on diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile index 255c7f685d..4f70bd75d2 100644 --- a/docs/doxygen/Doxyfile +++ b/docs/doxygen/Doxyfile @@ -185,6 +185,11 @@ INPUT = \ $(PROJECT_PATH)/components/esp_wifi/include/esp_wifi_default.h \ $(PROJECT_PATH)/components/esp_wifi/include/esp_wifi_types.h \ $(PROJECT_PATH)/components/esp_wifi/include/esp_wifi.h \ + $(PROJECT_PATH)/components/wpa_supplicant/esp_supplicant/include/esp_mbo.h \ + $(PROJECT_PATH)/components/wpa_supplicant/esp_supplicant/include/esp_eap_client.h \ + $(PROJECT_PATH)/components/wpa_supplicant/esp_supplicant/include/esp_rrm.h \ + $(PROJECT_PATH)/components/wpa_supplicant/esp_supplicant/include/esp_wnm.h \ + $(PROJECT_PATH)/components/wpa_supplicant/esp_supplicant/include/esp_wps.h \ $(PROJECT_PATH)/components/esp_wifi/wifi_apps/include/esp_nan.h \ $(PROJECT_PATH)/components/esp-tls/esp_tls_errors.h \ $(PROJECT_PATH)/components/esp-tls/esp_tls.h \ diff --git a/docs/en/api-reference/network/esp_wifi.rst b/docs/en/api-reference/network/esp_wifi.rst index 647f515118..2fc5e14890 100644 --- a/docs/en/api-reference/network/esp_wifi.rst +++ b/docs/en/api-reference/network/esp_wifi.rst @@ -28,3 +28,8 @@ API Reference .. include-build-file:: inc/esp_wifi.inc .. include-build-file:: inc/esp_wifi_types.inc +.. include-build-file:: inc/esp_eap_client.inc +.. include-build-file:: inc/esp_wps.inc +.. include-build-file:: inc/esp_rrm.inc +.. include-build-file:: inc/esp_wnm.inc +.. include-build-file:: inc/esp_mbo.inc diff --git a/docs/en/migration-guides/release-5.x/5.1/index.rst b/docs/en/migration-guides/release-5.x/5.1/index.rst index 4a3c4b65d7..b8689821db 100644 --- a/docs/en/migration-guides/release-5.x/5.1/index.rst +++ b/docs/en/migration-guides/release-5.x/5.1/index.rst @@ -11,3 +11,4 @@ Migration from 5.0 to 5.1 storage networking system + wifi diff --git a/docs/en/migration-guides/release-5.x/5.1/wifi.rst b/docs/en/migration-guides/release-5.x/5.1/wifi.rst new file mode 100644 index 0000000000..69ad9d00c2 --- /dev/null +++ b/docs/en/migration-guides/release-5.x/5.1/wifi.rst @@ -0,0 +1,10 @@ +WiFi +==== + +:link_to_translation:`zh_CN:[中文]` + + +WiFi Enterprise security +------------------------ + +APIs defined in `esp_wpa2.h` have been deprecated. Please use newer APIs from `esp_eap_client.h`. diff --git a/docs/zh_CN/migration-guides/release-5.x/5.1/index.rst b/docs/zh_CN/migration-guides/release-5.x/5.1/index.rst index c95cac366c..be372ff26a 100644 --- a/docs/zh_CN/migration-guides/release-5.x/5.1/index.rst +++ b/docs/zh_CN/migration-guides/release-5.x/5.1/index.rst @@ -11,3 +11,4 @@ storage networking system + wifi diff --git a/docs/zh_CN/migration-guides/release-5.x/5.1/wifi.rst b/docs/zh_CN/migration-guides/release-5.x/5.1/wifi.rst new file mode 100644 index 0000000000..dcc40433d9 --- /dev/null +++ b/docs/zh_CN/migration-guides/release-5.x/5.1/wifi.rst @@ -0,0 +1,10 @@ +WiFi +==== + +:link_to_translation:`en:[English]` + + +WiFi企业级安全 +------------------------ + +在 `esp_wpa2.h` 中定义的API已被弃用，请使用来自 `esp_eap_client.h` 的新API。