mirror of
https://github.com/espressif/esp-idf.git
synced 2024-09-20 00:36:01 -04:00
Merge branch 'docs/improve_blufi_docs' into 'master'
docs: update BluFi documentation regarding misleading contents Closes DOC-2836 and DOC-2701 See merge request espressif/esp-idf!18393
This commit is contained in:
Jiang Jiang Jian
commit
e4a70f311a
@ -5,18 +5,18 @@ BluFi
|
||||
Overview
|
||||
--------
|
||||
|
||||
The BluFi for {IDF_TARGET_NAME} is a Wi-Fi network configuration function via Bluetooth channel. It provides a secure protocol to pass Wi-Fi configuration and credentials to the {IDF_TARGET_NAME}. Using this information {IDF_TARGET_NAME} can then e.g. connect to an AP or establish a SoftAP.
|
||||
The BluFi for {IDF_TARGET_NAME} is a Wi-Fi network configuration function via Bluetooth channel. It provides a secure protocol to pass Wi-Fi configuration and credentials to {IDF_TARGET_NAME}. Using this information, {IDF_TARGET_NAME} can then connect to an AP or establish a SoftAP.
|
||||
|
||||
Fragmenting, data encryption, checksum verification in the BluFi layer are the key elements of this process.
|
||||
Fragmenting, data encryption, and checksum verification in the BluFi layer are the key elements of this process.
|
||||
|
||||
You can customize symmetric encryption, asymmetric encryption and checksum support customization. Here we use the DH algorithm for key negotiation, 128-AES algorithm for data encryption, and CRC16 algorithm for checksum verification.
|
||||
You can customize symmetric encryption, asymmetric encryption, and checksum support customization. Here we use the DH algorithm for key negotiation, 128-AES algorithm for data encryption, and CRC16 algorithm for checksum verification.
|
||||
|
||||
The BluFi Flow
|
||||
---------------
|
||||
|
||||
The BluFi networking flow includes the configuration of the SoftAP and Station.
|
||||
|
||||
The following uses Station as an example to illustrate the core parts of the procedure, including broadcast, connection, service discovery, negotiation of the shared key, data transmission, connection status backhaul.
|
||||
The following uses Station as an example to illustrate the core parts of the procedure, including broadcast, connection, service discovery, negotiation of the shared key, data transmission, and connection status backhaul.
|
||||
|
||||
1. Set the {IDF_TARGET_NAME} into GATT Server mode and then it will send broadcasts with specific *advertising data*. You can customize this broadcast as needed, which is not a part of the BluFi Profile.
|
||||
|
||||
@ -26,7 +26,7 @@ The following uses Station as an example to illustrate the core parts of the pro
|
||||
|
||||
4. After {IDF_TARGET_NAME} receives the data frame of key negotiation, it will parse the content according to the user-defined negotiation method.
|
||||
|
||||
5. The mobile phone works with {IDF_TARGET_NAME} for key negotiation using the encryption algorithms such as DH, RSA or ECC.
|
||||
5. The mobile phone works with {IDF_TARGET_NAME} for key negotiation using the encryption algorithms, such as DH, RSA, or ECC.
|
||||
|
||||
6. After the negotiation process is completed, the mobile phone will send a control frame for security-mode setup to {IDF_TARGET_NAME}.
|
||||
|
||||
@ -36,7 +36,7 @@ The following uses Station as an example to illustrate the core parts of the pro
|
||||
|
||||
9. The mobile phone sends a control frame of Wi-Fi connection request to {IDF_TARGET_NAME}. When receiving this control frame, {IDF_TARGET_NAME} will regard the communication of essential information as done and get ready to connect to the Wi-Fi.
|
||||
|
||||
10. After connecting to the Wi-Fi, {IDF_TARGET_NAME} will send a control frame of Wi-Fi connection status report to the mobile phone，to report the connection status. At this point the networking procedure is completed.
|
||||
10. After connecting to the Wi-Fi, {IDF_TARGET_NAME} will send a control frame of Wi-Fi connection status report to the mobile phone. At this point, the networking procedure is completed.
|
||||
|
||||
.. note::
|
||||
|
||||
@ -78,80 +78,80 @@ The Frame Formats Defined in BluFi
|
||||
|
||||
The frame formats for the communication between the mobile phone App and {IDF_TARGET_NAME} are defined as follows:
|
||||
|
||||
The frame format with no fragment (8 bit)：
|
||||
The frame format with no fragment:
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 25 25
|
||||
|
||||
* - Description
|
||||
- Value
|
||||
* - Field
|
||||
- Value (Byte)
|
||||
* - Type (Least Significant Bit)
|
||||
- 1
|
||||
- 1
|
||||
* - Frame Control
|
||||
- 1
|
||||
* - Sequence Number
|
||||
- 1
|
||||
- 1
|
||||
* - Data Length
|
||||
- 1
|
||||
- 1
|
||||
* - Data
|
||||
- ${Data Length}
|
||||
- ${Data Length}
|
||||
* - CheckSum (Most Siginificant Bit)
|
||||
- 2
|
||||
- 2
|
||||
|
||||
If the **Frame Ctrl** bit is enabled, the **Total length** bit indicates the length of remaining part of the frame. It can tell the remote how much memory needs to be alloced.
|
||||
If the frag frame bit in the **Frame Control** field is enabled, there would be a 2-byte **Total Content Length** field in the **Data** field. This **Total Content Length** field indicates the length of the remaining part of the frame and also tells the remote how much memory needs to be allocated.
|
||||
|
||||
The frame format with fragments（8 bit）：
|
||||
The frame format with fragments:
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 25 25
|
||||
|
||||
* - Description
|
||||
- Value
|
||||
* - Field
|
||||
- Value (Byte)
|
||||
* - Type (Least Significant Bit)
|
||||
- 1
|
||||
- 1
|
||||
* - Frame Control (Frag)
|
||||
- 1
|
||||
- 1
|
||||
* - Sequence Number
|
||||
- 1
|
||||
- 1
|
||||
* - Data Length
|
||||
- 1
|
||||
- 1
|
||||
* - Data
|
||||
- * Total Content Length: 2
|
||||
* Content: ${Data Length} - 2
|
||||
* Content: ${Data Length} - 2
|
||||
* - CheckSum (Most Siginificant Bit)
|
||||
- 2
|
||||
- 2
|
||||
|
||||
Normally, the control frame does not contain data bits, except for ACK Frame.
|
||||
|
||||
The format of ACK Frame（8 bit）：
|
||||
The format of ACK Frame:
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 25 25
|
||||
|
||||
* - Description
|
||||
- Value
|
||||
* - Field
|
||||
- Value (Byte)
|
||||
* - Type - ACK (Least Significant Bit)
|
||||
- 1
|
||||
- 1
|
||||
* - Frame Control
|
||||
- 1
|
||||
- 1
|
||||
* - Sequence Number
|
||||
- 1
|
||||
- 1
|
||||
* - Data Length
|
||||
- 1
|
||||
- 1
|
||||
* - Data
|
||||
- Acked Sequence Number: 2
|
||||
- Acked Sequence Number: 2
|
||||
* - CheckSum (Most Siginificant Bit)
|
||||
- 2
|
||||
- 2
|
||||
|
||||
|
||||
1. Type
|
||||
|
||||
The **Type** field, taking 1 byte, is divided into **Type** and **Subtype**, that Type uses the lower 2 bits and **Subtype** uses the upper 6 bits.
|
||||
**Type** field takes 1 byte and is divided into **Type** and **Subtype**. **Type** uses the lower two bits, indicating whether the frame is a data frame or a control frame. **Subtype** uses the upper six bits, indicating the specific meaning of this data frame or control frame.
|
||||
|
||||
* The control frame is not encrypted for the time being and supports to be verified;
|
||||
* The control frame is not encrypted for the time being and supports to be verified.
|
||||
|
||||
* The data frame supports to be encrypted and verified.
|
||||
|
||||
@ -172,11 +172,11 @@ The format of ACK Frame（8 bit）：
|
||||
- The data field consumes a byte and its value is the same as the sequence field of the frame to reply to.
|
||||
|
||||
* - 0x1 (b’000001)
|
||||
- Set ESP device to the security mode.
|
||||
- To inform ESP device of the security mode to use when sending data, which is allowed to be reset multiple times during the process. Each setting affects the subsequent security mode used.
|
||||
- Set the ESP device to the security mode.
|
||||
- To inform the ESP device of the security mode to use when sending data, which is allowed to be reset multiple times during the process. Each setting affects the subsequent security mode used.
|
||||
|
||||
If it is not set, ESP device will send the control frame and data frame with no checksum and encryption by default. The data transmission from the mobile phone to ESP device is controlled by this control frame.
|
||||
- The data field consumes a byte. The higher 4 bits are for the security mode setting of the control frame, and the lower 4 bits are for the security mode setting of the data frame.
|
||||
If it is not set, the ESP device will send the control frame and data frame with no checksum and encryption by default. The data transmission from the mobile phone to the ESP device is controlled by this control frame.
|
||||
- The data field consumes a byte. The higher four bits are for the security mode setting of the control frame, and the lower four bits are for the security mode setting of the data frame.
|
||||
|
||||
* b’0000: no checksum and no encryption;
|
||||
* b’0001: with checksum but no encryption;
|
||||
@ -185,7 +185,7 @@ The format of ACK Frame（8 bit）：
|
||||
|
||||
* - 0x2 (b’000010)
|
||||
- Set the opmode of Wi-Fi.
|
||||
- The frame contains opmode settings for configuring the Wi-Fi mode of ESP device.
|
||||
- The frame contains opmode settings for configuring the Wi-Fi mode of the ESP device.
|
||||
- data[0] is for opmode settings, including:
|
||||
|
||||
* 0x00: NULL
|
||||
@ -196,25 +196,25 @@ The format of ACK Frame（8 bit）：
|
||||
Please set the SSID/Password/Max Connection Number of the AP mode in the first place if an AP gets involved.
|
||||
|
||||
* - 0x3 (b’000011)
|
||||
- Connect ESP device to the AP.
|
||||
- To notify ESP device that the essential information has been sent and it is allowed to connect to the AP.
|
||||
- Connect the ESP device to the AP.
|
||||
- To notify the ESP device that the essential information has been sent and it is allowed to connect to the AP.
|
||||
- No data field is contained.
|
||||
|
||||
* - 0x4 (b’000100)
|
||||
- Disconnect ESP device from the AP.
|
||||
- Disconnect the ESP device from the AP.
|
||||
-
|
||||
- No data field is contained.
|
||||
|
||||
* - 0x5 (b’000101)
|
||||
- To get the information of ESP device’s Wi-Fi mode and it’s status.
|
||||
- To get the information of the ESP device’s Wi-Fi mode and it’s status.
|
||||
-
|
||||
- * No data field is contained. When receiving this control frame, ESP device will send back a follow-up frame of Wi-Fi connection state report to the mobile phone with the information of the current opmode, connection status, SSID and so on.
|
||||
- * No data field is contained. When receiving this control frame, the ESP device will send back a follow-up frame of Wi-Fi connection state report to the mobile phone with the information of the current opmode, connection status, SSID, and so on.
|
||||
* The types of information sent to the mobile phone is defined by the application installed on the phone.
|
||||
|
||||
* - 0x6 (b’000110)
|
||||
- Disconnect the STA device from the SoftAP (in SoftAP mode).
|
||||
-
|
||||
- Date[0~5] is taken as the MAC address for the STA device. If there is a second STA device, then it uses data[6-11] and the rest can be done in the same manner.
|
||||
- Data[0~5] is taken as the MAC address for the STA device. If there is a second STA device, then it uses data[6-11] and the rest can be done in the same manner.
|
||||
|
||||
* - 0x7 (b’000111)
|
||||
- Get the version information.
|
||||
@ -224,12 +224,12 @@ The format of ACK Frame（8 bit）：
|
||||
* - 0x8 (b’001000)
|
||||
- Disconnect the BLE GATT link.
|
||||
-
|
||||
- ESP device will disconnect the BLE GATT link after receives this command.
|
||||
- The ESP device will disconnect the BLE GATT link after receives this command.
|
||||
|
||||
* - 0x9 (b’001001)
|
||||
- Get the Wi-Fi list.
|
||||
- To get ESP device to scan the Wi-Fi access points around.
|
||||
- No data field is contained. When receiving this control frame, ESP device will send back a follow-up frame of Wi-Fi list report to the mobile phone.
|
||||
- To get the ESP device to scan the Wi-Fi access points around.
|
||||
- No data field is contained. When receiving this control frame, the ESP device will send back a follow-up frame of Wi-Fi list report to the mobile phone.
|
||||
|
||||
|
||||
|
||||
@ -248,7 +248,7 @@ The format of ACK Frame（8 bit）：
|
||||
- The negotiation data will be sent to the callback function registered in the application layer.
|
||||
- The length of the data depends on the length field.
|
||||
* - 0x1 (b’000001)
|
||||
- Send the BSSID for STA mode.
|
||||
- Send the SSID for STA mode.
|
||||
- To send the BSSID of the AP for the STA device to connect under the condition that the SSID is hidden.
|
||||
- Please refer to Note 1 below.
|
||||
* - 0x2 (b’000010)
|
||||
@ -272,7 +272,7 @@ The format of ACK Frame（8 bit）：
|
||||
-
|
||||
- data[0] represents the value of the connection number, ranging from 1 to 4. When the transmission direction is ESP device to the mobile phone, it means to provide the mobile phone with the needed information.
|
||||
* - 0x7 (b’000111)
|
||||
- Set the authentication mode for the SoftAP.
|
||||
- Set the authentication mode for SoftAP mode.
|
||||
-
|
||||
- data[0]：
|
||||
|
||||
@ -282,11 +282,11 @@ The format of ACK Frame（8 bit）：
|
||||
* 0x03: WPA2_PSK
|
||||
* 0x04: WPA_WPA2_PSK
|
||||
|
||||
When the transmission direction is ESP device to the mobile phone, it means to provide the mobile phone with the needed information.
|
||||
When the transmission direction is from the ESP device to the mobile phone, it means to provide the mobile phone with the needed information.
|
||||
* - 0x8 (b’001000)
|
||||
- Set the number of channels for SoftAP mode.
|
||||
-
|
||||
- data[0] represents the quantity of the supported channels, ranging from 1 to 14. When the transmission direction is ESP device to the mobile phone, it means to provide the mobile phone with the needed information.
|
||||
- data[0] represents the quantity of the supported channels, ranging from 1 to 14. When the transmission direction is from the ESP device to the mobile phone, it means to provide the mobile phone with the needed information.
|
||||
* - 0x9 (b’001001)
|
||||
- Username
|
||||
- It provides the username of the GATT client when using encryption of enterprise level.
|
||||
@ -321,9 +321,9 @@ The format of ACK Frame（8 bit）：
|
||||
* 0x02: SoftAP
|
||||
* 0x03: SoftAP & STA
|
||||
|
||||
data[1]：the connection state of the STA device, 0x0 indicates a connection state, and others represent a disconnected state;
|
||||
data[1]: connection state of the STA device. 0x0 indicates a connection state, and others represent a disconnected state;
|
||||
|
||||
data[2]：the connection state of the SoftAP, that is, how many STA devices have been connected.
|
||||
data[2]: connection state of SoftAP. That is, how many STA devices have been connected.
|
||||
|
||||
data[3] and the subsequent is in accordance with the format of SSID/BSSID information.
|
||||
* - 0x10 (b’010000)
|
||||
@ -334,7 +334,7 @@ The format of ACK Frame（8 bit）：
|
||||
* - 0x11 (b’010001)
|
||||
- Wi-Fi List
|
||||
- To send the Wi-Fi list to ESP device.
|
||||
- The format of the data frame is length + RSSI + SSID and it supports to be sent into fragments if the data length is too long.
|
||||
- The format of the data frame is length + RSSI + SSID. It supports to be sent into fragments if the data length is too long.
|
||||
* - 0x12 (b’010010)
|
||||
- Report Error
|
||||
- To notify the mobile phone that there is an error with BluFi.
|
||||
@ -354,13 +354,13 @@ The format of ACK Frame（8 bit）：
|
||||
|
||||
.. note::
|
||||
|
||||
- Note 1: The length of the data depends on the length field. When the transmission direction is ESP device to the mobile phone, it means to provide the mobile phone with the needed information.
|
||||
- Note 1: The length of the data depends on the data length field. When the transmission direction is from the ESP device to the mobile phone, it means to provide the mobile phone with the needed information.
|
||||
|
||||
- Note 2: The length of the data depends on the length field. The frame supports to be fragmented if the data length is not enough.
|
||||
- Note 2: The length of the data depends on the data length field. The frame supports to be fragmented if the data length is not long enough.
|
||||
|
||||
2. Frame Control
|
||||
|
||||
Control field, takes 1 byte and each bit has a different meaning.
|
||||
The **Frame Control** field takes one byte and each bit has a different meaning.
|
||||
|
||||
|
||||
.. list-table::
|
||||
@ -372,68 +372,68 @@ The format of ACK Frame（8 bit）：
|
||||
* - 0x01
|
||||
- Indicates whether the frame is encrypted.
|
||||
|
||||
* 1 means encryption
|
||||
* 0 means unencrypted
|
||||
* 1 means encrypted.
|
||||
* 0 means unencrypted.
|
||||
|
||||
The encrypted part of the frame includes the full clear data before the DATA field is encrypted (no checksum). Control frame is not encrypted, so this bit is 0.
|
||||
* - 0x02
|
||||
- The data field that indicates whether a frame contains a checksum (such as SHA1,MD5,CRC, etc.) for the end of the frame. Data field includes sequence + data length + clear text. Both the control frame and the data frame can contain a check bit or not.
|
||||
- Indicates whether a frame contains a checksum (such as SHA1, MD5, CRC) for the end of the frame. Data field includes sequence, data length, and clear text. Both the control frame and the data frame can choose whether to contain a check bit or not.
|
||||
* - 0x04
|
||||
- Represents the data direction.
|
||||
- Indicates the data direction.
|
||||
|
||||
* 0 means the mobile phone to ESP device;
|
||||
* 1 means ESP device to the mobile phone.
|
||||
* 0 means from the mobile phone to the ESP device.
|
||||
* 1 means from the ESP device to the mobile phone.
|
||||
* - 0x08
|
||||
- Indicates whether the other person is required to reply to an ACK.
|
||||
|
||||
* 0 indicates no requirement;
|
||||
* 1 indicates to reply ACK.
|
||||
* 0 indicates not required to reply to an ACK.
|
||||
* 1 indicates required to reply to an ACK.
|
||||
* - 0x10
|
||||
- Indicates whether there are subsequent data fragments.
|
||||
|
||||
* 0 indicates that there are no subsequent data fragments for this frame;
|
||||
* 1 indicates that there are subsequent data fragments and used to transmit longer data.
|
||||
* 0 indicates that there is no subsequent data fragment for this frame.
|
||||
* 1 indicates that there are subsequent data fragments which used to transmit longer data.
|
||||
|
||||
In the case of a frag frame, the total length of the current content section + subsequent content section is given, in the first 2 bytes of the data field (that is, the content data of the maximum support 64 K).
|
||||
In the case of a frag frame, the total length of the current content section + subsequent content section is given in the first two bytes of the data field (that is, the content data of the maximum support 64 K).
|
||||
* - 0x10~0x80
|
||||
- reserved
|
||||
- Reserved
|
||||
|
||||
3. Sequence Control
|
||||
3. Sequence Number
|
||||
|
||||
Sequence control field. When a frame is sent,the value of sequence fied is automatically incremented by 1 regardless of the type of frame, which prevents Replay Attack. The sequence is cleared after each reconnection.
|
||||
The **Sequence Number** field is the field for sequence control. When a frame is sent, the value of this field is automatically incremented by 1 regardless of the type of frame, which prevents Replay Attack. The sequence would be cleared after each reconnection.
|
||||
|
||||
4. Length
|
||||
4. Data Length
|
||||
|
||||
The length of the data field that does not include CheckSum.
|
||||
The **Data Length** field indicates the length of the data field, which does not include CheckSum.
|
||||
|
||||
5. Data
|
||||
|
||||
The instruction of the data field is different according to various values of Type or Subtype. Please refer to the table above.
|
||||
Content of the **Data** field can be different according to various values of Type or Subtype. Please refer to the table above.
|
||||
|
||||
6. CheckSum
|
||||
|
||||
This field takes 2 bytes that is used to check "sequence + data length + clear text data".
|
||||
The **CheckSum** field takes two bytes, which is used to check "sequence + data length + clear text data".
|
||||
|
||||
The Security Implementation of {IDF_TARGET_NAME}
|
||||
------------------------------------------------
|
||||
|
||||
1. Securing data
|
||||
1. Securing Data
|
||||
|
||||
To ensure that the transmission of the Wi-Fi SSID and password is secure, the message needs to be encrypted using symmetric encryption algorithms, such as AES, DES and so on. Before using symmetric encryption algorithms, the devices are required to negotiate (or generate) a shared key using an asymmetric encryption algorithm (DH, RSA, ECC, etc).
|
||||
To ensure that the transmission of the Wi-Fi SSID and password is secure, the message needs to be encrypted using symmetric encryption algorithms, such as AES, DES, and so on. Before using symmetric encryption algorithms, the devices are required to negotiate (or generate) a shared key using an asymmetric encryption algorithm (DH, RSA, ECC, etc).
|
||||
|
||||
2. Ensuring data integrity
|
||||
2. Ensuring Data Integrity
|
||||
|
||||
To ensure data integrity, you need to add a checksum algorithm, such as SHA1, MD5, CRC, etc.
|
||||
|
||||
3. Securing identity (signature)
|
||||
3. Securing Identity (Signature)
|
||||
|
||||
Algorithm like RSA can be used to secure identity. But for DH, it needs other algorithms as an companion for signature.
|
||||
|
||||
4. Replay attack prevention
|
||||
4. Replay Attack Prevention
|
||||
|
||||
It is added to the Sequence field and used during the checksum verification.
|
||||
It is added to the Sequence Number field and used during the checksum verification.
|
||||
|
||||
For the coding of {IDF_TARGET_NAME}, you can determine and develop the security processing, such as key negotiation. The mobile application sends the negotiation data to {IDF_TARGET_NAME} and then the data will be sent to the application layer for processing. If the application layer does not process it, you can use the DH encryption algorithm provided by BluFi to negotiate the key.
|
||||
For the coding of {IDF_TARGET_NAME}, you can determine and develop the security processing, such as key negotiation. The mobile application sends the negotiation data to {IDF_TARGET_NAME}, and then the data will be sent to the application layer for processing. If the application layer does not process it, you can use the DH encryption algorithm provided by BluFi to negotiate the key.
|
||||
|
||||
The application layer needs to register several security-related functions to BluFi:
|
||||
|
||||
@ -441,23 +441,23 @@ The Security Implementation of {IDF_TARGET_NAME}
|
||||
|
||||
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, and 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.
|
||||
|
||||
Here are two "*", because the length of the data to be emitted is unknown that requires the function to allocate itself (malloc) or point to the global variable, and to inform whether the memory needs to be freed by NEED_FREE.
|
||||
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 use the same length. The IV8 is a 8 bit sequence value of frames, which can be used as a 8 bit of IV.
|
||||
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 use the same length. The IV8 is a 8 bit sequence value of frames, which can be used as a 8 bit of IV.
|
||||
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
|
||||
|
||||
|
||||
@ -5,26 +5,26 @@ BluFi
|
||||
概览
|
||||
-----
|
||||
|
||||
BluFi 是一款基于蓝牙通道的 Wi-Fi 网络配置功能，适用于 {IDF_TARGET_NAME}。它通过安全协议将 Wi-Fi 的 SSID、密码等配置信息传输到 {IDF_TARGET_NAME}，然后 {IDF_TARGET_NAME} 可基于这些信息连接到 AP 或建立 SoftAP。
|
||||
BluFi 是一项基于蓝牙通道的 Wi-Fi 网络配置功能，适用于 {IDF_TARGET_NAME}。它通过安全协议将 Wi-Fi 的 SSID、密码等配置信息传输到 {IDF_TARGET_NAME}。基于这些信息，{IDF_TARGET_NAME} 可进而连接到 AP 或建立 SoftAP。
|
||||
|
||||
BluFi 流程的关键部分包括数据的分片、加密、校验和验证。
|
||||
BluFi 流程的关键部分包括数据的分片、加密以及校验和验证。
|
||||
|
||||
用户可按需自定义用于对称加密、非对称加密和校验的算法。这里我们采用 DH 算法进行密钥协商、128-AES 算法用于数据加密、CRC16 算法用于校验和验证。
|
||||
用户可按需自定义用于对称加密、非对称加密以及校验的算法。此处，我们采用 DH 算法进行密钥协商，128-AES 算法用于数据加密，CRC16 算法用于校验和验证。
|
||||
|
||||
BluFi 流程
|
||||
----------
|
||||
|
||||
BluFi 配网功能包含配置 SoftAP 和 Station 两部分。
|
||||
BluFi 配网流程包含配置 SoftAP 和配置 Station 两部分。
|
||||
|
||||
下面以配置 Station 为例说明配置步骤。BluFi 配网的配置 Station 包含广播、连接、服务发现、协商共享密钥、传输数据、回传连接状态等步骤。
|
||||
下面以配置 Station 为例，介绍了广播、连接、服务发现、协商共享密钥、传输数据、回传连接状态等关键步骤。
|
||||
|
||||
1. {IDF_TARGET_NAME} 开启 GATT Server 模式，发送带有特定 *advertising data* 的广播。你可以自定义该广播，该广播不属于 BluFi Profile。
|
||||
1. {IDF_TARGET_NAME} 开启 GATT Server 模式，发送带有特定 *advertising data* 的广播。该广播不属于 BluFi Profile，您可以按需对其进行自定义。
|
||||
|
||||
2. 使用手机 APP 搜索到该特定广播，手机作为 GATT Client 连接 {IDF_TARGET_NAME}。你可以决定使用哪款手机 APP。
|
||||
2. 使用手机应用程序搜索到该广播后，手机将作为 GATT Client 连接 {IDF_TARGET_NAME}。该步骤对具体使用哪款手机应用程序并无特殊要求。
|
||||
|
||||
3. GATT 连接建立成功后，手机会向 {IDF_TARGET_NAME} 发送数据帧进行密钥协商（详情见 :ref:`frame_formats` ）。
|
||||
3. 成功建立 GATT 连接后，手机会向 {IDF_TARGET_NAME} 发送数据帧进行密钥协商（详见 :ref:`frame_formats` ）。
|
||||
|
||||
4. {IDF_TARGET_NAME} 收到密钥协商的数据帧后，会按照使用者自定义的协商方法来解析。
|
||||
4. {IDF_TARGET_NAME} 收到密钥协商的数据帧后，会按照您自定义的协商方法进行解析。
|
||||
|
||||
5. 手机与 {IDF_TARGET_NAME} 进行密钥协商。协商过程可使用 DH/RSA/ECC 等加密算法。
|
||||
|
||||
@ -34,15 +34,15 @@ BluFi 配网功能包含配置 SoftAP 和 Station 两部分。
|
||||
|
||||
8. 手机向 {IDF_TARGET_NAME} 发送 :ref:`frame_formats` 中定义的数据帧，包括 SSID、密码等 Wi-Fi 配置信息。
|
||||
|
||||
9. 手机向 {IDF_TARGET_NAME} 发送 Wi-Fi 连接请求的控制帧。{IDF_TARGET_NAME} 收到这个控制帧之后，会认为手机已将必要的信息已经传输完毕，准备连接 Wi-Fi。
|
||||
9. 手机向 {IDF_TARGET_NAME} 发送 Wi-Fi 连接请求的控制帧。{IDF_TARGET_NAME} 收到控制帧后，即默认手机已完成必要信息的传输，准备连接 Wi-Fi。
|
||||
|
||||
10. {IDF_TARGET_NAME} 连接到 Wi-Fi 后，发送 Wi-Fi 连接状态报告的控制帧到手机，以报告连接状态。至此配网结束。
|
||||
10. 连接到 Wi-Fi 后，{IDF_TARGET_NAME} 发送 Wi-Fi 连接状态报告的控制帧到手机。至此，配网结束。
|
||||
|
||||
.. note::
|
||||
|
||||
1. {IDF_TARGET_NAME} 收到安全模式配置的控制帧后，会根据定义的安全模式进行相关操作。
|
||||
|
||||
2. 进行对称加密和解密时，加密和解密前后的数据长度必须一致，支持原地加密和解密。
|
||||
2. 进行对称加密和解密时，加密和解密前后的数据长度必须一致。支持原地加密和解密。
|
||||
|
||||
BluFi 流程图
|
||||
---------------
|
||||
@ -76,51 +76,51 @@ BluFi 流程图
|
||||
BluFi 中定义的帧格式
|
||||
----------------------------
|
||||
|
||||
手机 APP 与 {IDF_TARGET_NAME} 之间的 BluFi 通信格式定义如下：
|
||||
手机应用程序与 {IDF_TARGET_NAME} 之间的 BluFi 通信格式定义如下：
|
||||
|
||||
帧不分片情况下的格式 (8 位)：
|
||||
帧不分片格式：
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 25 25
|
||||
|
||||
* - 描述
|
||||
- 值
|
||||
* - 类型字段（最低有效位）
|
||||
* - 字段
|
||||
- 值（字节）
|
||||
* - 类型（最低有效位）
|
||||
- 1
|
||||
* - 帧控制
|
||||
- 1
|
||||
* - 帧控制字段
|
||||
- 1
|
||||
* - 序列号字段
|
||||
- 1
|
||||
* - 数据长度字段
|
||||
- 1
|
||||
* - 数据字段
|
||||
- ${Data Length}
|
||||
* - 校验字段（最高有效位）
|
||||
- 2
|
||||
* - 序列号
|
||||
- 1
|
||||
* - 数据长度
|
||||
- 1
|
||||
* - 数据
|
||||
- ${Data Length}
|
||||
* - 校验（最高有效位）
|
||||
- 2
|
||||
|
||||
如果使能 **帧控制** 位，则 **总长度** 位表示帧的剩余部分的总长度，用于报告终端需要分配多少内存。
|
||||
如果使能 **帧控制** 字段中的分片位，则 **数据** 字段中会出现 2 字节的 **内容总长度**。该 **内容总长度** 表示帧的剩余部分的总长度，并用于报告终端需要分配的内存大小。
|
||||
|
||||
帧分片格式（8 位）：
|
||||
帧分片格式：
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 25 25
|
||||
|
||||
* - 描述
|
||||
- 值
|
||||
* - 类型字段（最低有效位）
|
||||
* - 字段
|
||||
- 值（字节）
|
||||
* - 类型（最低有效位）
|
||||
- 1
|
||||
* - 帧控制字段（分片）
|
||||
* - 帧控制（分片）
|
||||
- 1
|
||||
* - 序列号字段
|
||||
* - 序列号
|
||||
- 1
|
||||
* - 数据长度字段
|
||||
* - 数据长度
|
||||
- 1
|
||||
* - 数据字段
|
||||
- * Total Content Length: 2
|
||||
* Content: ${Data Length} - 2
|
||||
* - 校验字段（最高有效位）
|
||||
* - 数据
|
||||
- * 内容总长度：2
|
||||
* 数据内容长度：${Data Length} - 2
|
||||
* - 校验（最高有效位）
|
||||
- 2
|
||||
|
||||
通常情况下，控制帧不包含数据位，ACK 帧类型除外。
|
||||
@ -131,31 +131,31 @@ ACK 帧格式（8 bit）：
|
||||
:header-rows: 1
|
||||
:widths: 25 25
|
||||
|
||||
* - 描述
|
||||
- 值
|
||||
* - 类型字段 - ACK（最低有效位）
|
||||
* - 字段
|
||||
- 值（字节）
|
||||
* - 类型 - ACK（最低有效位）
|
||||
- 1
|
||||
* - 帧控制字段
|
||||
* - 帧控制
|
||||
- 1
|
||||
* - 序列号字段
|
||||
* - 序列号
|
||||
- 1
|
||||
* - 数据长度字段
|
||||
* - 数据长度
|
||||
- 1
|
||||
* - 数据字段
|
||||
* - 数据
|
||||
- ACK 序列号: 2
|
||||
* - 校验字段（最高有效位）
|
||||
* - 校验（最高有效位）
|
||||
- 2
|
||||
|
||||
|
||||
1. 类型字段
|
||||
|
||||
类型字段，占 1 字节。分为类型字段和子类型字段两部分，类型字段占低 2 位，子类型字段占高 6 位。
|
||||
**类型** 字段占 1 字节，分为 **类型** 和 **子类型** 两部分。其中，**类型** 占低 2 位，表明该帧为数据帧或是控制帧；**子类型** 占高 6 位，表示此数据帧或者控制帧的具体含义。
|
||||
|
||||
* 控制帧，暂不进行加密，可校验；
|
||||
* 控制帧，暂不进行加密，可校验。
|
||||
|
||||
* 数据帧，可加密，可校验。
|
||||
|
||||
1.1 控制帧 (二进制：0x0 b’00)
|
||||
1.1 控制帧（二进制：0x0 b’00）
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
@ -173,7 +173,7 @@ ACK 帧格式（8 bit）：
|
||||
|
||||
* - 0x1 (b’000001)
|
||||
- 将 ESP 设备设置为安全模式。
|
||||
- 通知 ESP 设备发送数据时使用的安全模式，在数据发送过程中可多次重置，每次设置后会影响后续使用的安全模式。
|
||||
- 通知 ESP 设备发送数据时使用的安全模式，在数据发送过程中可多次重置。设置后，将影响后续使用的安全模式。
|
||||
|
||||
如果不设置，ESP 设备将默认发送不带校验和加密的控制帧和数据帧。从手机到 ESP 设备的数据传输是由这个控制帧控制的。
|
||||
- 数据字段占一个字节。高 4 位用于控制帧的安全模式设置，低 4 位用于数据帧的安全模式设置。
|
||||
@ -214,7 +214,7 @@ ACK 帧格式（8 bit）：
|
||||
* - 0x6 (b’000110)
|
||||
- 断开 STA 设备与 SoftAP 的连接（SoftAP 模式）。
|
||||
-
|
||||
- data[0~5] 为 STA 设备的 MAC 地址，如有多个 STA 设备，则第二个使用 data[6-11]，依次类推。
|
||||
- data[0~5] 为 STA 设备的 MAC 地址。如有多个 STA 设备，则第二个使用 data[6-11]，依次类推。
|
||||
|
||||
* - 0x7 (b’000111)
|
||||
- 获取版本信息。
|
||||
@ -282,11 +282,11 @@ ACK 帧格式（8 bit）：
|
||||
* 0x03: WPA2_PSK
|
||||
* 0x04: WPA_WPA2_PSK
|
||||
|
||||
当传输方向是 ESP 设备到手机时，表示向手机端提供所需信息。
|
||||
若传输方向是从 ESP 设备到手机，则表示向手机端提供所需信息。
|
||||
* - 0x8 (b’001000)
|
||||
- 设置 SoftAP 模式的通道数量。
|
||||
-
|
||||
- data[0] 代表支持的通道的数量，范围从 1 到 14。当传输方向是 ESP 设备到手机时，表示向手机端提供所需信息。
|
||||
- data[0] 代表支持的通道的数量，范围从 1 到 14。若传输方向是从 ESP 设备到手机，则表示向手机端提供所需信息。
|
||||
* - 0x9 (b’001001)
|
||||
- 用户名
|
||||
- 在进行企业级加密时提供 GATT 客户端的用户名。
|
||||
@ -321,7 +321,7 @@ ACK 帧格式（8 bit）：
|
||||
* 0x02: SoftAP
|
||||
* 0x03: SoftAP & STA
|
||||
|
||||
data[1]：STA 设备的连接状态，0x0 表示处于连接状态，其他表示处于非连接状态；
|
||||
data[1]：STA 设备的连接状态。0x0 表示处于连接状态，其他表示处于非连接状态；
|
||||
|
||||
data[2]：SoftAP 的连接状态，即表示有多少 STA 设备已经连接。
|
||||
|
||||
@ -334,7 +334,7 @@ ACK 帧格式（8 bit）：
|
||||
* - 0x11 (b’010001)
|
||||
- Wi-Fi 热点列表
|
||||
- 将 Wi-Fi 热点列表发送给 ESP 设备
|
||||
- 数据帧的格式为 length + RSSI + SSID，数据较长时可分片发送。
|
||||
- 数据帧的格式为 Length + RSSI + SSID。数据较长时可分片发送。
|
||||
* - 0x12 (b’010010)
|
||||
- 报告异常
|
||||
- 通知手机 BluFi 过程出现异常
|
||||
@ -354,7 +354,7 @@ ACK 帧格式（8 bit）：
|
||||
|
||||
.. note::
|
||||
|
||||
- 备注 1: 数据的长度取决于数据长度字段。当传输方向是 ESP 设备到手机时，表示向手机端提供所需信息。
|
||||
- 备注 1: 数据的长度取决于数据长度字段。若传输方向是从 ESP 设备到手机，则表示向手机端提供所需信息。
|
||||
|
||||
- 备注 2: 数据的长度取决于数据长度字段。如果数据长度不够，该帧可用分片。
|
||||
|
||||
@ -372,29 +372,29 @@ ACK 帧格式（8 bit）：
|
||||
* - 0x01
|
||||
- 表示帧是否加密。
|
||||
|
||||
* 1 表示加密
|
||||
* 0 表示未加密
|
||||
* 1 表示加密。
|
||||
* 0 表示未加密。
|
||||
|
||||
该帧的加密部分包括数据字段加密之前的完整明文数据（不包括校验部分）。控制帧暂不加密，故控制帧此位为 0。
|
||||
* - 0x02
|
||||
- 该数据字段表示帧尾是否包含校验位，如 SHA1、MD5、CRC 等。该数据字段包含序列 + 数据长度 + 明文。控制帧和数据帧都可以选择包含或不包含校验位。
|
||||
- 该数据字段表示帧尾是否包含校验位，如 SHA1、MD5、CRC 等。该数据字段包含序列、数据长度以及明文。控制帧和数据帧都可以选择包含或不包含校验位。
|
||||
* - 0x04
|
||||
- 表示数据方向。
|
||||
|
||||
* 0 表示传输方向是手机到 ESP 设备
|
||||
* 1 表示传输方向是 ESP 设备到手机
|
||||
* 0 表示传输方向是从手机到 ESP 设备。
|
||||
* 1 表示传输方向是从 ESP 设备到手机。
|
||||
* - 0x08
|
||||
- 表示是否要求对方回复 ACK。
|
||||
|
||||
* 0 表示不要求；
|
||||
* 0 表示不要求回复 ACK。
|
||||
* 1 表示要求回复 ACK。
|
||||
* - 0x10
|
||||
- 表示是否有后续的数据分片。
|
||||
|
||||
* 0 表示此帧没有后续数据分片；
|
||||
* 0 表示此帧没有后续数据分片。
|
||||
* 1 表示还有后续数据分片，用来传输较长的数据。
|
||||
|
||||
对于分片帧，在数据字段的前两个字节中会给定当前内容部分 + 随后内容部分的总长度（即最大支持 64 K 的数据内容）。
|
||||
对于分片帧，在数据字段的前两个字节中，会给定当前内容部分和随后内容部分的总长度（即最大支持 64 K 的数据内容）。
|
||||
* - 0x10~0x80
|
||||
- 保留
|
||||
|
||||
@ -412,7 +412,7 @@ ACK 帧格式（8 bit）：
|
||||
|
||||
6. 校验
|
||||
|
||||
此字段占两个字节，用来校验“序列 + 数据长度 + 明文数据”。
|
||||
此字段占两个字节，用来校验序列、数据长度以及明文。
|
||||
|
||||
{IDF_TARGET_NAME} 端的安全实现
|
||||
----------------------------------
|
||||
@ -427,7 +427,7 @@ ACK 帧格式（8 bit）：
|
||||
|
||||
3. 身份安全（签名）
|
||||
|
||||
某些算法如 RSA 可以保证身份安全。有些算法如 DH，本身不能保证身份安全，需要添加其他算法来签名。
|
||||
某些算法如 RSA 可以保证身份安全。但如 DH 这类的算法，本身不能保证身份安全，需要添加其他算法来签名。
|
||||
|
||||
4. 防止重放攻击 (Replay Attack)
|
||||
|
||||
@ -441,11 +441,11 @@ ACK 帧格式（8 bit）：
|
||||
|
||||
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。
|
||||
|
||||
这里的两个 “*”，因为需要发出去的数据长度未知，所以需要函数自行分配 (malloc) 或者指向全局变量，并告知是否需要通过 NEED_FREE 释放内存。
|
||||
这里的两个 “*” 是因为需要发出去的数据长度未知，所以需要函数自行分配 (malloc) 或者指向全局变量，并告知是否需要通过 NEED_FREE 释放内存。
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user