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