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