1 /*
2  * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #ifndef __ESP_BLUFI_API_H__
8 #define __ESP_BLUFI_API_H__
9 
10 #include "esp_err.h"
11 #include "esp_wifi_types.h"
12 
13 #ifdef __cplusplus
14 extern "C" {
15 #endif
16 
17 typedef enum {
18     ESP_BLUFI_EVENT_INIT_FINISH = 0,                     /*<! When BLUFI init complete, this event happen */
19     ESP_BLUFI_EVENT_DEINIT_FINISH,                       /*<! When BLUFI deinit complete, this event happen */
20     ESP_BLUFI_EVENT_SET_WIFI_OPMODE,                     /*<! When Phone set ESP32 wifi operation mode(AP/STA/AP_STA), this event happen */
21     ESP_BLUFI_EVENT_BLE_CONNECT,                         /*<! When Phone connect to ESP32 with BLE, this event happen */
22     ESP_BLUFI_EVENT_BLE_DISCONNECT,                      /*<! When Phone disconnect with BLE, this event happen */
23     ESP_BLUFI_EVENT_REQ_CONNECT_TO_AP,                   /*<! When Phone request ESP32's STA connect to AP, this event happen */
24     ESP_BLUFI_EVENT_REQ_DISCONNECT_FROM_AP,              /*<! When Phone request ESP32's STA disconnect from AP, this event happen */
25     ESP_BLUFI_EVENT_GET_WIFI_STATUS,                     /*<! When Phone get ESP32 wifi status, this event happen */
26     ESP_BLUFI_EVENT_DEAUTHENTICATE_STA,                  /*<! When Phone deauthenticate sta from SOFTAP, this event happen */
27     /* recv data */
28     ESP_BLUFI_EVENT_RECV_STA_BSSID,                      /*<! When Phone send STA BSSID to ESP32 to connect, this event happen */
29     ESP_BLUFI_EVENT_RECV_STA_SSID,                       /*<! When Phone send STA SSID to ESP32 to connect, this event happen */
30     ESP_BLUFI_EVENT_RECV_STA_PASSWD,                     /*<! When Phone send STA PASSWORD to ESP32 to connect, this event happen */
31     ESP_BLUFI_EVENT_RECV_SOFTAP_SSID,                    /*<! When Phone send SOFTAP SSID to ESP32 to start SOFTAP, this event happen */
32     ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD,                  /*<! When Phone send SOFTAP PASSWORD to ESP32 to start SOFTAP, this event happen */
33     ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM,            /*<! When Phone send SOFTAP max connection number to ESP32 to start SOFTAP, this event happen */
34     ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE,               /*<! When Phone send SOFTAP authentication mode to ESP32 to start SOFTAP, this event happen */
35     ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL,                 /*<! When Phone send SOFTAP channel to ESP32 to start SOFTAP, this event happen */
36     ESP_BLUFI_EVENT_RECV_USERNAME,                       /*<! When Phone send username to ESP32, this event happen */
37     ESP_BLUFI_EVENT_RECV_CA_CERT,                        /*<! When Phone send CA certificate to ESP32, this event happen */
38     ESP_BLUFI_EVENT_RECV_CLIENT_CERT,                    /*<! When Phone send Client certificate to ESP32, this event happen */
39     ESP_BLUFI_EVENT_RECV_SERVER_CERT,                    /*<! When Phone send Server certificate to ESP32, this event happen */
40     ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY,                /*<! When Phone send Client Private key to ESP32, this event happen */
41     ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY,                /*<! When Phone send Server Private key to ESP32, this event happen */
42     ESP_BLUFI_EVENT_RECV_SLAVE_DISCONNECT_BLE,           /*<! When Phone send Disconnect key to ESP32, this event happen */
43     ESP_BLUFI_EVENT_GET_WIFI_LIST,                       /*<! When Phone send get wifi list command to ESP32, this event happen */
44     ESP_BLUFI_EVENT_REPORT_ERROR,                        /*<! When Blufi report error, this event happen */
45     ESP_BLUFI_EVENT_RECV_CUSTOM_DATA,                    /*<! When Phone send custom data to ESP32, this event happen */
46 } esp_blufi_cb_event_t;
47 
48 /// BLUFI config status
49 typedef enum {
50     ESP_BLUFI_STA_CONN_SUCCESS = 0x00,
51     ESP_BLUFI_STA_CONN_FAIL    = 0x01,
52     ESP_BLUFI_STA_CONNECTING   = 0x02,
53     ESP_BLUFI_STA_NO_IP        = 0x03,
54 } esp_blufi_sta_conn_state_t;
55 
56 /// BLUFI init status
57 typedef enum {
58     ESP_BLUFI_INIT_OK = 0,
59     ESP_BLUFI_INIT_FAILED,
60 } esp_blufi_init_state_t;
61 
62 /// BLUFI deinit status
63 typedef enum {
64     ESP_BLUFI_DEINIT_OK = 0,
65     ESP_BLUFI_DEINIT_FAILED,
66 } esp_blufi_deinit_state_t;
67 
68 typedef enum {
69     ESP_BLUFI_SEQUENCE_ERROR = 0,
70     ESP_BLUFI_CHECKSUM_ERROR,
71     ESP_BLUFI_DECRYPT_ERROR,
72     ESP_BLUFI_ENCRYPT_ERROR,
73     ESP_BLUFI_INIT_SECURITY_ERROR,
74     ESP_BLUFI_DH_MALLOC_ERROR,
75     ESP_BLUFI_DH_PARAM_ERROR,
76     ESP_BLUFI_READ_PARAM_ERROR,
77     ESP_BLUFI_MAKE_PUBLIC_ERROR,
78     ESP_BLUFI_DATA_FORMAT_ERROR,
79     ESP_BLUFI_CALC_MD5_ERROR,
80     ESP_BLUFI_WIFI_SCAN_FAIL,
81     ESP_BLUFI_MSG_STATE_ERROR,
82 } esp_blufi_error_state_t;
83 
84 /**
85  * @brief BLUFI  extra information structure
86  */
87 typedef struct {
88     //station
89     uint8_t sta_bssid[6];           /*!< BSSID of station interface */
90     bool sta_bssid_set;             /*!< is BSSID of station interface set */
91     uint8_t *sta_ssid;              /*!< SSID of station interface */
92     int sta_ssid_len;               /*!< length of SSID of station interface */
93     uint8_t *sta_passwd;            /*!< password of station interface */
94     int sta_passwd_len;             /*!< length of password of station interface */
95     uint8_t *softap_ssid;           /*!< SSID of softap interface */
96     int softap_ssid_len;            /*!< length of SSID of softap interface */
97     uint8_t *softap_passwd;         /*!< password of station interface */
98     int softap_passwd_len;          /*!< length of password of station interface */
99     uint8_t softap_authmode;        /*!< authentication mode of softap interface */
100     bool softap_authmode_set;       /*!< is authentication mode of softap interface set */
101     uint8_t softap_max_conn_num;    /*!< max connection number of softap interface */
102     bool softap_max_conn_num_set;   /*!< is max connection number of softap interface set */
103     uint8_t softap_channel;         /*!< channel of softap interface */
104     bool softap_channel_set;        /*!< is channel of softap interface set */
105     uint8_t sta_max_conn_retry;     /*!< max retry of sta establish connection */
106     bool sta_max_conn_retry_set;    /*!< is max retry of sta establish connection set */
107     uint8_t sta_conn_end_reason;    /*!< reason of sta connection end */
108     bool sta_conn_end_reason_set;   /*!< is reason of sta connection end set */
109     int8_t sta_conn_rssi;           /*!< rssi of sta connection */
110     bool sta_conn_rssi_set;         /*!< is rssi of sta connection set */
111 } esp_blufi_extra_info_t;
112 
113 /** @brief Description of an WiFi AP */
114 typedef struct {
115     uint8_t ssid[33];                     /**< SSID of AP */
116     int8_t  rssi;                         /**< signal strength of AP */
117 } esp_blufi_ap_record_t;
118 
119 /// Bluetooth address length
120 #define ESP_BLUFI_BD_ADDR_LEN     6
121 /// Bluetooth device address
122 typedef uint8_t esp_blufi_bd_addr_t[ESP_BLUFI_BD_ADDR_LEN];
123 
124 /**
125  * @brief BLUFI callback parameters union
126  */
127 typedef union {
128     /**
129 	 * @brief ESP_BLUFI_EVENT_INIT_FINISH
130 	 */
131     struct blufi_init_finish_evt_param {
132         esp_blufi_init_state_t state;				/*!< Initial status */
133     } init_finish;									/*!< Blufi callback param of ESP_BLUFI_EVENT_INIT_FINISH */
134 
135     /**
136 	 * @brief ESP_BLUFI_EVENT_DEINIT_FINISH
137 	 */
138     struct blufi_deinit_finish_evt_param {
139         esp_blufi_deinit_state_t state;				/*!< De-initial status */
140     } deinit_finish;								/*!< Blufi callback param of ESP_BLUFI_EVENT_DEINIT_FINISH */
141 
142     /**
143      * @brief ESP_BLUFI_EVENT_SET_WIFI_MODE
144      */
145     struct blufi_set_wifi_mode_evt_param {
146         wifi_mode_t op_mode;                        /*!< Wifi operation mode */
147     } wifi_mode;									/*!< Blufi callback param of ESP_BLUFI_EVENT_INIT_FINISH */
148 
149     /**
150      * @brief ESP_BLUFI_EVENT_CONNECT
151 	 */
152     struct blufi_connect_evt_param {
153         esp_blufi_bd_addr_t remote_bda;                   /*!< Blufi Remote bluetooth device address */
154         uint8_t    server_if;                       /*!< server interface */
155         uint16_t   conn_id;                         /*!< Connection id */
156     } connect;									    /*!< Blufi callback param of ESP_BLUFI_EVENT_CONNECT */
157 
158     /**
159      * @brief ESP_BLUFI_EVENT_DISCONNECT
160 	 */
161     struct blufi_disconnect_evt_param {
162         esp_blufi_bd_addr_t remote_bda;                   /*!< Blufi Remote bluetooth device address */
163     } disconnect;									/*!< Blufi callback param of ESP_BLUFI_EVENT_DISCONNECT */
164 
165     /* ESP_BLUFI_EVENT_REQ_WIFI_CONNECT */          /* No callback param */
166     /* ESP_BLUFI_EVENT_REQ_WIFI_DISCONNECT */       /* No callback param */
167 
168     /**
169      * @brief ESP_BLUFI_EVENT_RECV_STA_BSSID
170      */
171     struct blufi_recv_sta_bssid_evt_param {
172         uint8_t bssid[6];                           /*!< BSSID */
173     } sta_bssid;                                    /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_STA_BSSID */
174 
175     /**
176      * @brief ESP_BLUFI_EVENT_RECV_STA_SSID
177      */
178     struct blufi_recv_sta_ssid_evt_param {
179         uint8_t *ssid;                              /*!< SSID */
180         int ssid_len;                               /*!< SSID length */
181     } sta_ssid;                                     /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_STA_SSID */
182 
183     /**
184      * @brief
185      * ESP_BLUFI_EVENT_RECV_STA_PASSWD
186      */
187     struct blufi_recv_sta_passwd_evt_param {
188         uint8_t *passwd;                            /*!< Password */
189         int passwd_len;                             /*!< Password Length */
190     } sta_passwd;                                   /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_STA_PASSWD */
191 
192     /**
193      * @brief ESP_BLUFI_EVENT_RECV_SOFTAP_SSID
194      */
195     struct blufi_recv_softap_ssid_evt_param {
196         uint8_t *ssid;                              /*!< SSID */
197         int ssid_len;                               /*!< SSID length */
198     } softap_ssid;                                  /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_SSID */
199 
200     /**
201      * @brief
202      * ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD
203      */
204     struct blufi_recv_softap_passwd_evt_param {
205         uint8_t *passwd;                            /*!< Password */
206         int passwd_len;                             /*!< Password Length */
207     } softap_passwd;                                /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD */
208 
209     /**
210      * @brief ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM
211      */
212     struct blufi_recv_softap_max_conn_num_evt_param {
213         int max_conn_num;                           /*!< SSID */
214     } softap_max_conn_num;                          /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM */
215 
216     /**
217      * @brief
218      * ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE
219      */
220     struct blufi_recv_softap_auth_mode_evt_param {
221         wifi_auth_mode_t auth_mode;                 /*!< Authentication mode */
222     } softap_auth_mode;                             /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE */
223 
224     /**
225      * @brief
226      * ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL
227      */
228     struct blufi_recv_softap_channel_evt_param {
229         uint8_t channel;                            /*!< Authentication mode */
230     } softap_channel;                             /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL */
231 
232     /**
233      * @brief ESP_BLUFI_EVENT_RECV_USERNAME
234      */
235     struct blufi_recv_username_evt_param {
236         uint8_t *name;                              /*!< Username point */
237         int name_len;                               /*!< Username length */
238     } username;                                     /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_USERNAME*/
239 
240     /**
241      * @brief ESP_BLUFI_EVENT_RECV_CA_CERT
242      */
243     struct blufi_recv_ca_evt_param {
244         uint8_t *cert;                              /*!< CA certificate point */
245         int cert_len;                               /*!< CA certificate length */
246     } ca;                                           /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_CA_CERT */
247 
248     /**
249      * ESP_BLUFI_EVENT_RECV_CLIENT_CERT
250      */
251     struct blufi_recv_client_cert_evt_param {
252         uint8_t *cert;                              /*!< Client certificate point */
253         int cert_len;                               /*!< Client certificate length */
254     } client_cert;                                  /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_CLIENT_CERT */
255 
256     /**
257      * ESP_BLUFI_EVENT_RECV_SERVER_CERT
258      */
259     struct blufi_recv_server_cert_evt_param {
260         uint8_t *cert;                              /*!< Client certificate point */
261         int cert_len;                               /*!< Client certificate length */
262     } server_cert;                                  /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_SERVER_CERT */
263 
264     /**
265      * ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY
266      */
267     struct blufi_recv_client_pkey_evt_param {
268         uint8_t *pkey;                              /*!< Client Private Key point, if Client certificate not contain Key */
269         int pkey_len;                               /*!< Client Private key length */
270     } client_pkey;                                  /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY */
271     /**
272      * ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY
273      */
274     struct blufi_recv_server_pkey_evt_param {
275         uint8_t *pkey;                              /*!< Client Private Key point, if Client certificate not contain Key */
276         int pkey_len;                               /*!< Client Private key length */
277     } server_pkey;                                  /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY */
278     /**
279      * @brief
280      * ESP_BLUFI_EVENT_REPORT_ERROR
281      */
282     struct blufi_get_error_evt_param {
283         esp_blufi_error_state_t state;              /*!< Blufi error state */
284     } report_error;                                 /*!< Blufi callback param of ESP_BLUFI_EVENT_REPORT_ERROR */
285     /**
286      * @brief
287      * ESP_BLUFI_EVENT_RECV_CUSTOM_DATA
288      */
289     struct blufi_recv_custom_data_evt_param {
290         uint8_t *data;                              /*!< Custom data */
291         uint32_t data_len;                          /*!< Custom data Length */
292     } custom_data;                                  /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_CUSTOM_DATA */
293 } esp_blufi_cb_param_t;
294 
295 /**
296  * @brief BLUFI event callback function type
297  * @param event : Event type
298  * @param param : Point to callback parameter, currently is union type
299  */
300 typedef void (* esp_blufi_event_cb_t)(esp_blufi_cb_event_t event, esp_blufi_cb_param_t *param);
301 
302 /* security function declare */
303 
304 /**
305  * @brief BLUFI negotiate data handler
306  * @param data : data from phone
307  * @param len  : length of data from phone
308  * @param output_data : data want to send to phone
309  * @param output_len : length of data want to send to phone
310  * @param need_free : output reporting if memory needs to be freed or not *
311  */
312 typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t **output_data, int *output_len, bool *need_free);
313 
314 /**
315  * @brief BLUFI  encrypt the data after negotiate a share key
316  * @param iv8  : initial vector(8bit), normally, blufi core will input packet sequence number
317  * @param crypt_data : plain text and encrypted data, the encrypt function must support autochthonous encrypt
318  * @param crypt_len  : length of plain text
319  * @return  Nonnegative number is encrypted length, if error, return negative number;
320  */
321 typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len);
322 
323 /**
324  * @brief BLUFI  decrypt the data after negotiate a share key
325  * @param iv8  : initial vector(8bit), normally, blufi core will input packet sequence number
326  * @param crypt_data : encrypted data and plain text, the encrypt function must support autochthonous decrypt
327  * @param crypt_len  : length of encrypted text
328  * @return  Nonnegative number is decrypted length, if error, return negative number;
329  */
330 typedef int (* esp_blufi_decrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len);
331 
332 /**
333  * @brief BLUFI  checksum
334  * @param iv8  : initial vector(8bit), normally, blufi core will input packet sequence number
335  * @param data : data need to checksum
336  * @param len  : length of data
337  */
338 typedef uint16_t (*esp_blufi_checksum_func_t)(uint8_t iv8, uint8_t *data, int len);
339 
340 /**
341  * @brief BLUFI  callback functions type
342  */
343 typedef struct {
344     esp_blufi_event_cb_t                event_cb;                   /*!< BLUFI event callback */
345     esp_blufi_negotiate_data_handler_t  negotiate_data_handler;     /*!< BLUFI negotiate data function for negotiate share key */
346     esp_blufi_encrypt_func_t            encrypt_func;               /*!< BLUFI encrypt data function with share key generated by negotiate_data_handler */
347     esp_blufi_decrypt_func_t            decrypt_func;               /*!< BLUFI decrypt data function with share key generated by negotiate_data_handler */
348     esp_blufi_checksum_func_t           checksum_func;              /*!< BLUFI check sum function (FCS) */
349 } esp_blufi_callbacks_t;
350 
351 /**
352  *
353  * @brief           This function is called to receive blufi callback event
354  *
355  * @param[in]       callbacks: callback functions
356  *
357  * @return          ESP_OK - success, other - failed
358  *
359  */
360 esp_err_t esp_blufi_register_callbacks(esp_blufi_callbacks_t *callbacks);
361 
362 /**
363  *
364  * @brief           This function is called to initialize blufi_profile
365  *
366  * @return          ESP_OK - success, other - failed
367  *
368  */
369 esp_err_t esp_blufi_profile_init(void);
370 
371 /**
372  *
373  * @brief           This function is called to de-initialize blufi_profile
374  *
375  * @return          ESP_OK - success, other - failed
376  *
377  */
378 esp_err_t esp_blufi_profile_deinit(void);
379 
380 /**
381  *
382  * @brief           This function is called to send wifi connection report
383  * @param opmode :  wifi opmode
384  * @param sta_conn_state   : station is already in connection or not
385  * @param softap_conn_num  : softap connection number
386  * @param extra_info       : extra information, such as sta_ssid, softap_ssid and etc.
387  *
388  * @return          ESP_OK - success, other - failed
389  *
390  */
391 esp_err_t esp_blufi_send_wifi_conn_report(wifi_mode_t opmode, esp_blufi_sta_conn_state_t sta_conn_state, uint8_t softap_conn_num, esp_blufi_extra_info_t *extra_info);
392 
393 /**
394  *
395  * @brief           This function is called to send wifi list
396  * @param apCount :  wifi list count
397  * @param list   : wifi list
398  *
399  * @return          ESP_OK - success, other - failed
400  *
401  */
402 esp_err_t esp_blufi_send_wifi_list(uint16_t apCount, esp_blufi_ap_record_t *list);
403 
404 /**
405  *
406  * @brief           Get BLUFI profile version
407  *
408  * @return          Most 8bit significant is Great version, Least 8bit is Sub version
409  *
410  */
411 uint16_t esp_blufi_get_version(void);
412 
413 /**
414  *
415  * @brief           This function is called to send blufi error information
416  * @param state :  error state
417  *
418  * @return          ESP_OK - success, other - failed
419  *
420  */
421 esp_err_t esp_blufi_send_error_info(esp_blufi_error_state_t state);
422 /**
423  *
424  * @brief           This function is called to custom data
425  * @param data :  custom data value
426  * @param data_len :  the length of custom data
427  *
428  * @return          ESP_OK - success, other - failed
429  *
430  */
431 esp_err_t esp_blufi_send_custom_data(uint8_t *data, uint32_t data_len);
432 #ifdef __cplusplus
433 }
434 #endif
435 
436 #endif /* _ESP_BLUFI_API_ */
437