1 /* 2 * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #pragma once 8 9 #include <stdbool.h> 10 #include "esp_err.h" 11 12 #ifdef __cplusplus 13 extern "C" { 14 #endif 15 16 /** 17 * @brief Enumeration of phase 2 authentication types for EAP-TTLS. 18 * 19 * This enumeration defines the supported phase 2 authentication methods 20 * that can be used in the EAP-TTLS (Extensible Authentication Protocol - 21 * Tunneled Transport Layer Security) protocol for the second authentication 22 * phase. 23 */ 24 typedef enum { 25 ESP_EAP_TTLS_PHASE2_EAP, /**< EAP (Extensible Authentication Protocol) */ 26 ESP_EAP_TTLS_PHASE2_MSCHAPV2, /**< MS-CHAPv2 (Microsoft Challenge Handshake Authentication Protocol - Version 2) */ 27 ESP_EAP_TTLS_PHASE2_MSCHAP, /**< MS-CHAP (Microsoft Challenge Handshake Authentication Protocol) */ 28 ESP_EAP_TTLS_PHASE2_PAP, /**< PAP (Password Authentication Protocol) */ 29 ESP_EAP_TTLS_PHASE2_CHAP /**< CHAP (Challenge Handshake Authentication Protocol) */ 30 } esp_eap_ttls_phase2_types; 31 32 /** 33 * @brief Configuration settings for EAP-FAST 34 * (Extensible Authentication Protocol - Flexible Authentication via Secure Tunneling). 35 * 36 * This structure defines the configuration options that can be used to customize the behavior of the 37 * EAP-FAST authentication protocol, specifically for Fast Provisioning and PAC (Protected Access Credential) handling. 38 */ 39 typedef struct { 40 int fast_provisioning; /**< Enable or disable Fast Provisioning in EAP-FAST (0 = disabled, 1 = enabled) */ 41 int fast_max_pac_list_len; /**< Maximum length of the PAC (Protected Access Credential) list */ 42 bool fast_pac_format_binary; /**< Set to true for binary format PAC, false for ASCII format PAC */ 43 } esp_eap_fast_config; 44 45 46 /** 47 * @brief Enable EAP authentication(WiFi Enterprise) for the station mode. 48 * 49 * This function enables Extensible Authentication Protocol (EAP) authentication 50 * for the Wi-Fi station mode. When EAP authentication is enabled, the ESP device 51 * will attempt to authenticate with the configured EAP credentials when connecting 52 * to a secure Wi-Fi network. 53 * 54 * @note Before calling this function, ensure that the Wi-Fi configuration and EAP 55 * credentials (such as username and password) have been properly set using the 56 * appropriate configuration APIs. 57 * 58 * @return 59 * - ESP_OK: EAP authentication enabled successfully. 60 * - ESP_ERR_NO_MEM: Failed to enable EAP authentication due to memory allocation failure. 61 */ 62 esp_err_t esp_wifi_sta_enterprise_enable(void); 63 64 65 /** 66 * @brief Disable EAP authentication(WiFi Enterprise) for the station mode. 67 * 68 * This function disables Extensible Authentication Protocol (EAP) authentication 69 * for the Wi-Fi station mode. When EAP authentication is disabled, the ESP device 70 * will not attempt to authenticate using EAP credentials when connecting to a 71 * secure Wi-Fi network. 72 * 73 * @note Disabling EAP authentication may cause the device to connect to the Wi-Fi 74 * network using other available authentication methods, if configured using esp_wifi_set_config(). 75 * 76 * @return 77 * - ESP_OK: EAP authentication disabled successfully. 78 * - ESP_ERR_INVALID_STATE: EAP client is in an invalid state for disabling. 79 */ 80 esp_err_t esp_wifi_sta_enterprise_disable(void); 81 82 /** 83 * @brief Set identity for PEAP/TTLS authentication method. 84 * 85 * This function sets the identity to be used during PEAP/TTLS authentication. 86 * 87 * @param[in] identity Pointer to the identity data. 88 * @param[in] len Length of the identity data (limited to 1~127 bytes). 89 * 90 * @return 91 * - ESP_OK: The identity was set successfully. 92 * - ESP_ERR_INVALID_ARG: Invalid argument (len <= 0 or len >= 128). 93 * - ESP_ERR_NO_MEM: Memory allocation failure. 94 */ 95 esp_err_t esp_eap_client_set_identity(const unsigned char *identity, int len); 96 97 /** 98 * @brief Clear the previously set identity for PEAP/TTLS authentication. 99 * 100 * This function clears the identity that was previously set for the EAP client. 101 * After calling this function, the EAP client will no longer use the previously 102 * configured identity during the authentication process. 103 */ 104 void esp_eap_client_clear_identity(void); 105 106 /** 107 * @brief Set username for PEAP/TTLS authentication method. 108 * 109 * This function sets the username to be used during PEAP/TTLS authentication. 110 * 111 * @param[in] username Pointer to the username data. 112 * @param[in] len Length of the username data (limited to 1~127 bytes). 113 * 114 * @return 115 * - ESP_OK: The username was set successfully. 116 * - ESP_ERR_INVALID_ARG: Failed due to an invalid argument (len <= 0 or len >= 128). 117 * - ESP_ERR_NO_MEM: Failed due to memory allocation failure. 118 */ 119 esp_err_t esp_eap_client_set_username(const unsigned char *username, int len); 120 121 /** 122 * @brief Clear username for PEAP/TTLS method. 123 * 124 * This function clears the previously set username for the EAP client. 125 */ 126 void esp_eap_client_clear_username(void); 127 128 /** 129 * @brief Set password for PEAP/TTLS authentication method. 130 * 131 * This function sets the password to be used during PEAP/TTLS authentication. 132 * 133 * @param[in] password Pointer to the password data. 134 * @param[in] len Length of the password data (len > 0). 135 * 136 * @return 137 * - ESP_OK: The password was set successfully. 138 * - ESP_ERR_INVALID_ARG: Failed due to an invalid argument (len <= 0). 139 * - ESP_ERR_NO_MEM: Failed due to memory allocation failure. 140 */ 141 esp_err_t esp_eap_client_set_password(const unsigned char *password, int len); 142 143 /** 144 * @brief Clear password for PEAP/TTLS method. 145 * 146 * This function clears the previously set password for the EAP client. 147 */ 148 void esp_eap_client_clear_password(void); 149 150 /** 151 * @brief Set a new password for MSCHAPv2 authentication method. 152 * 153 * This function sets the new password to be used during MSCHAPv2 authentication. 154 * The new password is used to substitute the old password when an eap-mschapv2 failure request 155 * message with error code ERROR_PASSWD_EXPIRED is received. 156 * 157 * @param[in] new_password Pointer to the new password data. 158 * @param[in] len Length of the new password data. 159 * 160 * @return 161 * - ESP_OK: The new password was set successfully. 162 * - ESP_ERR_INVALID_ARG: Failed due to an invalid argument (len <= 0). 163 * - ESP_ERR_NO_MEM: Failed due to memory allocation failure. 164 */ 165 esp_err_t esp_eap_client_set_new_password(const unsigned char *new_password, int len); 166 167 /** 168 * @brief Clear new password for MSCHAPv2 method. 169 * 170 * This function clears the previously set new password for the EAP client. 171 */ 172 void esp_eap_client_clear_new_password(void); 173 174 /** 175 * @brief Set CA certificate for EAP authentication. 176 * 177 * This function sets the Certificate Authority (CA) certificate to be used during EAP authentication. 178 * The CA certificate is passed to the EAP client module through a global pointer. 179 * 180 * @param[in] ca_cert Pointer to the CA certificate data. 181 * @param[in] ca_cert_len Length of the CA certificate data. 182 * 183 * @return 184 * - ESP_OK: The CA certificate was set successfully. 185 */ 186 esp_err_t esp_eap_client_set_ca_cert(const unsigned char *ca_cert, int ca_cert_len); 187 188 /** 189 * @brief Clear the previously set Certificate Authority (CA) certificate for EAP authentication. 190 * 191 * This function clears the CA certificate that was previously set for the EAP client. 192 * After calling this function, the EAP client will no longer use the previously 193 * configured CA certificate during the authentication process. 194 */ 195 void esp_eap_client_clear_ca_cert(void); 196 197 /** 198 * @brief Set client certificate and private key for EAP authentication. 199 * 200 * This function sets the client certificate and private key to be used during authentication. 201 * Optionally, a private key password can be provided for encrypted private keys. 202 * 203 * @attention 1. The client certificate, private key, and private key password are provided as pointers 204 * to the respective data arrays. 205 * @attention 2. The client_cert, private_key, and private_key_password should be zero-terminated. 206 * 207 * @param[in] client_cert Pointer to the client certificate data. 208 * @param[in] client_cert_len Length of the client certificate data. 209 * @param[in] private_key Pointer to the private key data. 210 * @param[in] private_key_len Length of the private key data (limited to 1~4096 bytes). 211 * @param[in] private_key_password Pointer to the private key password data (optional). 212 * @param[in] private_key_passwd_len Length of the private key password data (can be 0 for no password). 213 * 214 * @return 215 * - ESP_OK: The certificate, private key, and password (if provided) were set successfully. 216 */ 217 esp_err_t esp_eap_client_set_certificate_and_key(const unsigned char *client_cert, int client_cert_len, 218 const unsigned char *private_key, int private_key_len, 219 const unsigned char *private_key_password, int private_key_passwd_len); 220 221 /** 222 * @brief Clear the previously set client certificate and private key for EAP authentication. 223 * 224 * This function clears the client certificate and private key that were previously set 225 * for the EAP client. After calling this function, the EAP client will no longer use the 226 * previously configured certificate and private key during the authentication process. 227 */ 228 void esp_eap_client_clear_certificate_and_key(void); 229 230 /** 231 * @brief Set EAP client certificates time check (disable or not). 232 * 233 * This function enables or disables the time check for EAP client certificates. 234 * When disabled, the certificates' expiration time will not be checked during the authentication process. 235 * 236 * @param[in] disable True to disable EAP client certificates time check, false to enable it. 237 * 238 * @return 239 * - ESP_OK: The EAP client certificates time check setting was updated successfully. 240 */ 241 esp_err_t esp_eap_client_set_disable_time_check(bool disable); 242 243 /** 244 * @brief Get EAP client certificates time check status. 245 * 246 * This function retrieves the current status of the EAP client certificates time check. 247 * 248 * @param[out] disable Pointer to a boolean variable to store the disable status. 249 * 250 * @return 251 * - ESP_OK: The status of EAP client certificates time check was retrieved successfully. 252 */ 253 esp_err_t esp_eap_client_get_disable_time_check(bool *disable); 254 255 /** 256 * @brief Set EAP-TTLS phase 2 method. 257 * 258 * This function sets the phase 2 method to be used during EAP-TTLS authentication. 259 * 260 * @param[in] type The type of phase 2 method to be used (e.g., EAP, MSCHAPv2, MSCHAP, PAP, CHAP). 261 * 262 * @return 263 * - ESP_OK: The EAP-TTLS phase 2 method was set successfully. 264 */ 265 esp_err_t esp_eap_client_set_ttls_phase2_method(esp_eap_ttls_phase2_types type); 266 267 /** 268 * @brief Enable or disable Suite-B 192-bit certification checks. 269 * 270 * This function enables or disables the 192-bit Suite-B certification checks during EAP-TLS authentication. 271 * Suite-B is a set of cryptographic algorithms which generally are considered more secure. 272 * 273 * @param[in] enable True to enable 192-bit Suite-B certification checks, false to disable it. 274 * 275 * @return 276 * - ESP_OK: The 192-bit Suite-B certification checks were set successfully. 277 */ 278 esp_err_t esp_eap_client_set_suiteb_192bit_certification(bool enable); 279 280 /** 281 * @brief Set the PAC (Protected Access Credential) file for EAP-FAST authentication. 282 * 283 * EAP-FAST requires a PAC file that contains the client's credentials. 284 * 285 * @attention 1. For files read from the file system, length has to be decremented by 1 byte. 286 * @attention 2. Disabling the ESP_WIFI_MBEDTLS_TLS_CLIENT config is required to use EAP-FAST. 287 * 288 * @param[in] pac_file Pointer to the PAC file buffer. 289 * @param[in] pac_file_len Length of the PAC file buffer. 290 * 291 * @return 292 * - ESP_OK: The PAC file for EAP-FAST authentication was set successfully. 293 */ 294 esp_err_t esp_eap_client_set_pac_file(const unsigned char *pac_file, int pac_file_len); 295 296 /** 297 * @brief Set the parameters for EAP-FAST Phase 1 authentication. 298 * 299 * EAP-FAST supports Fast Provisioning, where clients can be authenticated faster using precomputed keys (PAC). 300 * This function allows configuring parameters for Fast Provisioning. 301 * 302 * @attention 1. Disabling the ESP_WIFI_MBEDTLS_TLS_CLIENT config is required to use EAP-FAST. 303 * 304 * @param[in] config Configuration structure with Fast Provisioning parameters. 305 * 306 * @return 307 * - ESP_OK: The parameters for EAP-FAST Phase 1 authentication were set successfully. 308 */ 309 esp_err_t esp_eap_client_set_fast_params(esp_eap_fast_config config); 310 311 /** 312 * @brief Use the default certificate bundle for EAP authentication. 313 * 314 * By default, the EAP client uses a built-in certificate bundle for server verification. 315 * Enabling this option allows the use of the default certificate bundle. 316 * 317 * @param[in] use_default_bundle True to use the default certificate bundle, false to use a custom bundle. 318 * 319 * @return 320 * - ESP_OK: The option to use the default certificate bundle was set successfully. 321 */ 322 esp_err_t esp_eap_client_use_default_cert_bundle(bool use_default_bundle); 323 324 #ifdef __cplusplus 325 } 326 #endif 327