Mirrors/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-10-03 03:31:41 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update CN translation and improve formatting

Browse Source 
(cherry picked from commit feff20614e)

Co-authored-by: Zhang Shuxian <zhangshuxian@espressif.com>
This commit is contained in:
Zhang Hai Peng
2025-12-11 16:21:51 +08:00
co-authored by Zhang Shuxian
parent 1fd2f90326
commit e81aea9f7b
2 changed files with 69 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/api-guides/ble/blufi.rst
+34 -53
View File
@@ -16,11 +16,7 @@ You can customize symmetric encryption, asymmetric encryption, and checksum supp
**BluFi is currently in maintenance mode, and no new features are planned.**
For new projects or when adding Wi-Fi provisioning, we recommend using the network_provisioning component
(`network_provisioning <https://github.com/espressif/idf-extra-components/tree/master/network_provisioning>`_)
for a modern, secure, and actively maintained solution.
For new projects or when adding Wi-Fi provisioning, we recommend using the `network_provisioning`_ component, which offers a modern, secure, and actively maintained solution.
Getting Started
@@ -675,64 +671,46 @@ The Security Implementation of {IDF_TARGET_NAME}
The application layer needs to register several security-related functions to BluFi:
.. code-block:: c
.. code-block:: c
typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t **output_data, int *output_len, bool *need_free)
typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t **output_data, int *output_len, bool *need_free)
This function is for {IDF_TARGET_NAME} to receive normal data during negotiation. After processing is completed, the data will be transmitted using Output_data and Output_len.
This function is for {IDF_TARGET_NAME} to receive normal data during negotiation. After processing is completed, the data will be transmitted using Output_data and Output_len.
BluFi will send output_data from Negotiate_data_handler after Negotiate_data_handler is called.
BluFi will send output_data from Negotiate_data_handler after Negotiate_data_handler is called.
Here are two "*", which means the length of the data to be emitted is unknown. Therefore, it requires the function to allocate itself (malloc) or point to the global variable to inform whether the memory needs to be freed by NEED_FREE.
.. code-block:: c
typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len)
The data to be encrypted and decrypted must be in the same length. The IV8 is an 8-bit sequence value of frames, which can be used as a 8-bit of IV.
.. code-block:: c
typedef int (* esp_blufi_decrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len)
The data to be encrypted and decrypted must be in the same length. The IV8 is an 8-bit sequence value of frames, which can be used as an 8-bit of IV.
.. code-block:: c
typedef uint16_t (*esp_blufi_checksum_func_t)(uint8_t iv8, uint8_t *data, int len)
This function is used to compute CheckSum and return a value of CheckSum. BluFi uses the returned value to compare the CheckSum of the frame.
5. BLE SMP Encryption for Blufi
Before Wi-Fi provisioning, you can use BLE SMP pairing to establish a secure connection, making the provisioning process safer.
This feature can be enabled or disabled via the configuration option:
.. code-block:: c
CONFIG_EXAMPLE_BLUFI_BLE_SMP_ENABLE
If this option is enabled, the ESP32 device will issue a pairing request once it is connected. Only after a successful pairing can the device proceed with provisioning.
Currently, BLE SMP pairing is supported **only on the Bluedroid host**.
6. Implementing Stronger Security
The default encryption and decryption logic in this example is intended for demonstration purposes only.
If you require a higher level of security, you may consider one of the following approaches:
1. **Custom Security Callbacks** – Implement your own encryption, decryption, authentication, and checksum algorithms by customizing the security callbacks in the Blufi framework:
Here are two ``*``, which means the length of the data to be emitted is unknown. Therefore, it requires the function to allocate itself (malloc) or point to the global variable to inform whether the memory needs to be freed by NEED_FREE.
.. code-block:: c
esp_err_t esp_blufi_register_callbacks(esp_blufi_callbacks_t *callbacks);
typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len)
2. **Network Provisioning Component (recommended)** – Alternatively, you can use the network_provisioning component for a secure, ready-to-use provisioning solution:
The data to be encrypted and decrypted must be in the same length. The IV8 is an 8-bit sequence value of frames, which can be used as a 8-bit of IV.
`network_provisioning <https://github.com/espressif/idf-extra-components/tree/master/network_provisioning>`_
.. code-block:: c
typedef int (* esp_blufi_decrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len)
The data to be encrypted and decrypted must be in the same length. The IV8 is an 8-bit sequence value of frames, which can be used as an 8-bit of IV.
.. code-block:: c
typedef uint16_t (*esp_blufi_checksum_func_t)(uint8_t iv8, uint8_t *data, int len)
This function is used to compute CheckSum and return a value of CheckSum. BluFi uses the returned value to compare the CheckSum of the frame.
5. Implementing Stronger Security
The default encryption and decryption logic in this example is intended for demonstration purposes only. If your application requires stronger security guarantees, consider one of the following approaches:
- **Custom Security Callbacks**: Implement your own encryption, decryption, authentication, and checksum algorithms by defining custom security callbacks in the Blufi framework:
.. code-block:: c
esp_err_t esp_blufi_register_callbacks(esp_blufi_callbacks_t *callbacks);
- **Network Provisioning Component (recommended)**: For a more robust, secure, and production-ready provisioning solution, consider using the `network_provisioning`_ component.
GATT Related Instructions
@@ -746,3 +724,6 @@ BluFi Service UUID: 0xFFFF, 16 bit
BluFi (the mobile > {IDF_TARGET_NAME}): 0xFF01, writable
Blufi ({IDF_TARGET_NAME} > the mobile phone): 0xFF02, readable and callable
.. _network_provisioning: https://github.com/espressif/idf-extra-components/tree/master/network_provisioning