docs: Update CN translation and improve formatting
(cherry picked from commit feff20614e4408aa3682ab88bf389f8db58b890e) Co-authored-by: Zhang Shuxian <zhangshuxian@espressif.com>
This commit is contained in:
Zhang Hai Peng
@@ -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
|
||||
----------------------------
|
||||
@@ -745,3 +723,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
|
||||
|
||||
@@ -14,13 +14,9 @@ BluFi 流程的关键部分包括数据的分片、加密以及校验和验证
|
||||
|
||||
.. note::
|
||||
|
||||
**BluFi 目前处于维护模式，不再规划新功能。**
|
||||
**BluFi 目前处于维护模式，暂不计划增加新功能。**
|
||||
|
||||
对于新项目或新增 Wi-Fi 配网的场景，建议使用 network_provisioning 组件
|
||||
|
||||
(`network_provisioning <https://github.com/espressif/idf-extra-components/tree/master/network_provisioning>`_)
|
||||
|
||||
来实现现代化、安全且有持续维护的解决方案。
|
||||
对于新项目或需要添加 Wi-Fi 配网功能的场景，建议使用 `network_provisioning`_ 组件。该组件更加现代、安全，并且仍在积极维护中。
|
||||
|
||||
|
||||
快速入门
|
||||
@@ -675,64 +671,46 @@ ACK 帧格式 (8 bit)：
|
||||
|
||||
应用层需向 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)
|
||||
|
||||
该函数用来接收协商期间的正常数据 (normal data)。数据处理完成后，需要将待发送的数据使用 output_data 和 output_len 传出。
|
||||
该函数用来接收协商期间的正常数据 (normal data)。数据处理完成后，需要将待发送的数据使用 output_data 和 output_len 传出。
|
||||
|
||||
BluFi 会在调用完 Negotiate_data_handler 后，发送 Negotiate_data_handler 传出的 output_data。
|
||||
BluFi 会在调用完 Negotiate_data_handler 后，发送 Negotiate_data_handler 传出的 output_data。
|
||||
|
||||
这里的两个 “*” 是因为需要发出去的数据长度未知，所以需要函数自行分配 (malloc) 或者指向全局变量，并告知是否需要通过 NEED_FREE 释放内存。
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len)
|
||||
|
||||
加密和解密的数据长度必须一致。其中 IV8 为帧的 8 位序列，可作为 IV 的某 8 个位来使用。
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
typedef int (* esp_blufi_decrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len)
|
||||
|
||||
加密和解密的数据长度必须一致。其中 IV8 为帧的 8 位序列，可作为 IV 的某 8 个位来使用。
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
typedef uint16_t (*esp_blufi_checksum_func_t)(uint8_t iv8, uint8_t *data, int len)
|
||||
|
||||
该函数用来进行校验，返回值为校验的值。BluFi 会使用该函数返回值与帧的校验值进行比较。
|
||||
|
||||
5. BLE SMP Encryption for Blufi
|
||||
|
||||
在 Wi-Fi 配网之前，可以使用 BLE SMP 配对建立安全连接，使配网过程更安全。
|
||||
|
||||
此功能可通过配置选项启用或禁用：
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
CONFIG_EXAMPLE_BLUFI_BLE_SMP_ENABLE
|
||||
|
||||
如果启用该选项，ESP32 设备在连接成功后会发起配对请求。仅在配对成功后，设备才可继续进行 Wi-Fi 配网。
|
||||
|
||||
目前 BLE SMP 配对 **仅支持 Bluedroid 主机**。
|
||||
|
||||
6. 实现更强的安全性
|
||||
|
||||
示例中的默认加密/解密逻辑仅用于演示目的。
|
||||
|
||||
如果需要更高等级的安全性，可以考虑以下方法：
|
||||
|
||||
1. **自定义安全回调** – 通过自定义 BluFi 框架中的安全回调函数，实现自己的加密、解密、认证以及校验算法：
|
||||
这里的两个 ``*`` 是因为需要发出去的数据长度未知，所以需要函数自行分配 (malloc) 或者指向全局变量，并告知是否需要通过 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 组件（推荐使用）** – 或者可以使用 ESP-IDF 提供的 network_provisioning 组件，实现安全、可直接使用的配网解决方案：
|
||||
加密和解密的数据长度必须一致。其中 IV8 为帧的 8 位序列，可作为 IV 的某 8 个位来使用。
|
||||
|
||||
`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)
|
||||
|
||||
加密和解密的数据长度必须一致。其中 IV8 为帧的 8 位序列，可作为 IV 的某 8 个位来使用。
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
typedef uint16_t (*esp_blufi_checksum_func_t)(uint8_t iv8, uint8_t *data, int len)
|
||||
|
||||
该函数用来进行校验，返回值为校验的值。BluFi 会使用该函数返回值与帧的校验值进行比较。
|
||||
|
||||
|
||||
5. 实现更强的安全性
|
||||
|
||||
示例中的默认加密、解密逻辑仅用于演示目的。如果你的应用需要更高的安全保障，可选择以下任一方法：
|
||||
|
||||
- **自定义安全回调**：通过改写 BluFi 框架中的安全回调函数，自定义加密、解密、认证以及校验算法：
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
esp_err_t esp_blufi_register_callbacks(esp_blufi_callbacks_t *callbacks);
|
||||
|
||||
- **网络配网组件（推荐使用）**：使用 ESP-IDF 提供的 `network_provisioning`_ 组件，实现安全、可直接使用的配网解决方案。
|
||||
|
||||
|
||||
GATT 相关说明
|
||||
@@ -746,3 +724,6 @@ BluFi Service UUID： 0xFFFF，16 bit
|
||||
BluFi（手机 > {IDF_TARGET_NAME}）特性：0xFF01，主要权限：可写
|
||||
|
||||
BluFi（{IDF_TARGET_NAME} > 手机）特性：0xFF02，主要权限：可读可通知
|
||||
|
||||
|
||||
.. _network_provisioning: https://github.com/espressif/idf-extra-components/tree/master/network_provisioning
|
||||
|
||||
Reference in New Issue
Block a user