1 /* 2 * SPDX-FileCopyrightText: 2019-2022 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef _ESP_WPA2_H 8 #define _ESP_WPA2_H 9 10 #include <stdbool.h> 11 12 #include "esp_err.h" 13 14 typedef enum { 15 ESP_EAP_TTLS_PHASE2_EAP, 16 ESP_EAP_TTLS_PHASE2_MSCHAPV2, 17 ESP_EAP_TTLS_PHASE2_MSCHAP, 18 ESP_EAP_TTLS_PHASE2_PAP, 19 ESP_EAP_TTLS_PHASE2_CHAP 20 } esp_eap_ttls_phase2_types; 21 22 typedef struct { 23 int fast_provisioning; 24 int fast_max_pac_list_len; 25 bool fast_pac_format_binary; 26 } esp_eap_fast_config; 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 /** 33 * @brief Enable wpa2 enterprise authentication. 34 * 35 * @attention 1. wpa2 enterprise authentication can only be used when ESP32 station is enabled. 36 * @attention 2. wpa2 enterprise authentication can only support TLS, PEAP-MSCHAPv2 and TTLS-MSCHAPv2 method. 37 * 38 * @return 39 * - ESP_OK: succeed. 40 * - ESP_ERR_NO_MEM: fail(internal memory malloc fail) 41 */ 42 esp_err_t esp_wifi_sta_wpa2_ent_enable(void); 43 44 /** 45 * @brief Disable wpa2 enterprise authentication. 46 * 47 * @attention 1. wpa2 enterprise authentication can only be used when ESP32 station is enabled. 48 * @attention 2. wpa2 enterprise authentication can only support TLS, PEAP-MSCHAPv2 and TTLS-MSCHAPv2 method. 49 * 50 * @return 51 * - ESP_OK: succeed. 52 */ 53 esp_err_t esp_wifi_sta_wpa2_ent_disable(void); 54 55 /** 56 * @brief Set identity for PEAP/TTLS method. 57 * 58 * @attention The API only passes the parameter identity to the global pointer variable in wpa2 enterprise module. 59 * 60 * @param identity: point to address where stores the identity; 61 * @param len: length of identity, limited to 1~127 62 * 63 * @return 64 * - ESP_OK: succeed 65 * - ESP_ERR_INVALID_ARG: fail(len <= 0 or len >= 128) 66 * - ESP_ERR_NO_MEM: fail(internal memory malloc fail) 67 */ 68 esp_err_t esp_wifi_sta_wpa2_ent_set_identity(const unsigned char *identity, int len); 69 70 /** 71 * @brief Clear identity for PEAP/TTLS method. 72 */ 73 void esp_wifi_sta_wpa2_ent_clear_identity(void); 74 75 /** 76 * @brief Set username for PEAP/TTLS method. 77 * 78 * @attention The API only passes the parameter username to the global pointer variable in wpa2 enterprise module. 79 * 80 * @param username: point to address where stores the username; 81 * @param len: length of username, limited to 1~127 82 * 83 * @return 84 * - ESP_OK: succeed 85 * - ESP_ERR_INVALID_ARG: fail(len <= 0 or len >= 128) 86 * - ESP_ERR_NO_MEM: fail(internal memory malloc fail) 87 */ 88 esp_err_t esp_wifi_sta_wpa2_ent_set_username(const unsigned char *username, int len); 89 90 /** 91 * @brief Clear username for PEAP/TTLS method. 92 */ 93 void esp_wifi_sta_wpa2_ent_clear_username(void); 94 95 /** 96 * @brief Set password for PEAP/TTLS method.. 97 * 98 * @attention The API only passes the parameter password to the global pointer variable in wpa2 enterprise module. 99 * 100 * @param password: point to address where stores the password; 101 * @param len: length of password(len > 0) 102 * 103 * @return 104 * - ESP_OK: succeed 105 * - ESP_ERR_INVALID_ARG: fail(len <= 0) 106 * - ESP_ERR_NO_MEM: fail(internal memory malloc fail) 107 */ 108 esp_err_t esp_wifi_sta_wpa2_ent_set_password(const unsigned char *password, int len); 109 110 /** 111 * @brief Clear password for PEAP/TTLS method.. 112 */ 113 void esp_wifi_sta_wpa2_ent_clear_password(void); 114 115 /** 116 * @brief Set new password for MSCHAPv2 method.. 117 * 118 * @attention 1. The API only passes the parameter password to the global pointer variable in wpa2 enterprise module. 119 * @attention 2. The new password is used to substitute the old password when eap-mschapv2 failure request message with error code ERROR_PASSWD_EXPIRED is received. 120 * 121 * @param new_password: point to address where stores the password; 122 * @param len: length of password 123 * 124 * @return 125 * - ESP_OK: succeed 126 * - ESP_ERR_INVALID_ARG: fail(len <= 0) 127 * - ESP_ERR_NO_MEM: fail(internal memory malloc fail) 128 */ 129 130 esp_err_t esp_wifi_sta_wpa2_ent_set_new_password(const unsigned char *new_password, int len); 131 132 /** 133 * @brief Clear new password for MSCHAPv2 method.. 134 */ 135 void esp_wifi_sta_wpa2_ent_clear_new_password(void); 136 137 /** 138 * @brief Set CA certificate for PEAP/TTLS method. 139 * 140 * @attention 1. The API only passes the parameter ca_cert to the global pointer variable in wpa2 enterprise module. 141 * @attention 2. The ca_cert should be zero terminated. 142 * 143 * @param ca_cert: point to address where stores the CA certificate; 144 * @param ca_cert_len: length of ca_cert 145 * 146 * @return 147 * - ESP_OK: succeed 148 */ 149 esp_err_t esp_wifi_sta_wpa2_ent_set_ca_cert(const unsigned char *ca_cert, int ca_cert_len); 150 151 /** 152 * @brief Clear CA certificate for PEAP/TTLS method. 153 */ 154 void esp_wifi_sta_wpa2_ent_clear_ca_cert(void); 155 156 /** 157 * @brief Set client certificate and key. 158 * 159 * @attention 1. The API only passes the parameter client_cert, private_key and private_key_passwd to the global pointer variable in wpa2 enterprise module. 160 * @attention 2. The client_cert, private_key and private_key_passwd should be zero terminated. 161 * 162 * @param client_cert: point to address where stores the client certificate; 163 * @param client_cert_len: length of client certificate; 164 * @param private_key: point to address where stores the private key; 165 * @param private_key_len: length of private key, limited to 1~2048; 166 * @param private_key_password: point to address where stores the private key password; 167 * @param private_key_password_len: length of private key password; 168 * 169 * @return 170 * - ESP_OK: succeed 171 */ 172 esp_err_t esp_wifi_sta_wpa2_ent_set_cert_key(const unsigned char *client_cert, int client_cert_len, const unsigned char *private_key, int private_key_len, const unsigned char *private_key_passwd, int private_key_passwd_len); 173 174 /** 175 * @brief Clear client certificate and key. 176 */ 177 void esp_wifi_sta_wpa2_ent_clear_cert_key(void); 178 179 /** 180 * @brief Set wpa2 enterprise certs time check(disable or not). 181 * 182 * @param true: disable wpa2 enterprise certs time check 183 * @param false: enable wpa2 enterprise certs time check 184 * 185 * @return 186 * - ESP_OK: succeed 187 */ 188 esp_err_t esp_wifi_sta_wpa2_ent_set_disable_time_check(bool disable); 189 190 /** 191 * @brief Get wpa2 enterprise certs time check(disable or not). 192 * 193 * @param disable: store disable value 194 * 195 * @return 196 * - ESP_OK: succeed 197 */ 198 esp_err_t esp_wifi_sta_wpa2_ent_get_disable_time_check(bool *disable); 199 200 /** 201 * @brief Set wpa2 enterprise ttls phase2 method 202 * 203 * @param type: the type of phase 2 method to be used 204 * 205 * @return 206 * - ESP_OK: succeed 207 */ 208 esp_err_t esp_wifi_sta_wpa2_ent_set_ttls_phase2_method(esp_eap_ttls_phase2_types type); 209 210 /** 211 * @brief enable/disable 192 bit suite b certification checks 212 * 213 * @param enable: bool to enable/disable it. 214 * 215 * @return 216 * - ESP_OK: succeed 217 */ 218 esp_err_t esp_wifi_sta_wpa2_set_suiteb_192bit_certification(bool enable); 219 220 /** 221 * @brief Set client pac file 222 * 223 * @attention 1. For files read from the file system, length has to be decremented by 1 byte. 224 * @attention 2. Disabling the WPA_MBEDTLS_CRYPTO config is required to use EAP-FAST. 225 * 226 * @param pac_file: pointer to the pac file 227 * pac_file_len: length of the pac file 228 * 229 * @return 230 * - ESP_OK: succeed 231 * - ESP_ERR_NO_MEM: fail(internal memory malloc fail) 232 */ 233 esp_err_t esp_wifi_sta_wpa2_ent_set_pac_file(const unsigned char *pac_file, int pac_file_len); 234 235 /** 236 * @brief Set Phase 1 parameters for EAP-FAST 237 * 238 * @attention 1. Disabling the WPA_MBEDTLS_CRYPTO config is required to use EAP-FAST. 239 * 240 * @param config: eap fast phase 1 configuration 241 * 242 * @return 243 * - ESP_OK: succeed 244 * - ESP_ERR_INVALID_ARG: fail(out of bound arguments) 245 * - ESP_ERR_NO_MEM: fail(internal memory malloc fail) 246 */ 247 esp_err_t esp_wifi_sta_wpa2_ent_set_fast_phase1_params(esp_eap_fast_config config); 248 249 #ifdef __cplusplus 250 } 251 #endif 252 #endif 253
