alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge branch 'component_bt/add_spp_faq_v4.2' into 'release/v4.2'

Browse Source 
Component_bt/Add FAQ in SPP Demo README[backport v4.2]

See merge request espressif/esp-idf!14797
This commit is contained in:
Wang Meng Yang 2021-08-23 05:16:29 +00:00
commit 94cdecde30
6 changed files with 286 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
components/bt/host/bluedroid/stack/include/stack/hcidefs.h
View File

@ -800,7 +800,7 @@
#define HCI_ERR_SCO_AIR_MODE 0x1D #define HCI_ERR_SCO_AIR_MODE 0x1D
#define HCI_ERR_INVALID_LMP_PARAM 0x1E #define HCI_ERR_INVALID_LMP_PARAM 0x1E
#define HCI_ERR_UNSPECIFIED 0x1F #define HCI_ERR_UNSPECIFIED 0x1F
#define HCI_ERR_UNSUPPORTED_LMP_FEATURE 0x20 #define HCI_ERR_UNSUPPORTED_LMP_PARAMETERS 0x20
#define HCI_ERR_ROLE_CHANGE_NOT_ALLOWED 0x21 #define HCI_ERR_ROLE_CHANGE_NOT_ALLOWED 0x21
#define HCI_ERR_LMP_RESPONSE_TIMEOUT 0x22 #define HCI_ERR_LMP_RESPONSE_TIMEOUT 0x22
#define HCI_ERR_LMP_ERR_TRANS_COLLISION 0x23 #define HCI_ERR_LMP_ERR_TRANS_COLLISION 0x23

179
examples/bluetooth/bluedroid/classic_bt/bt_spp_acceptor/ESP32_SSP.md Normal file
View File

@ -0,0 +1,179 @@
# ESP32 Classic Bluetooth Security - Secure Simple Pairing
This document briefly describes how the device io capability and security mask affect the process of the Secure Simple Pairing. It will help you figure out how to set the parameter when calling `esp_bt_gap_set_security_param`, or the parameter `sec_mask` when you want to establish a connection associate a certain profile, for example, an SPP connection.
## IO Capability
Input and output capabilities of a device are combined to generate its IO capabilities. The input capabilities are described in Table 1 The output capabilities are described in Table 2. Table 3 shows the combination of Input and Output Capability, which are defined as `ESP_BT_IO_CAP_OUT`, `ESP_BT_IO_CAP_IO`, `ESP_BT_IO_CAP_IN` and `ESP_BT_IO_CAP_NONE` in `esp_gap_bt_api.h`.
| Input Capability | Description |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No input | Device does not have the ability to indicate 'yes' or 'no' |
| Yes / No | Device has at least two buttons that can be easily mapped to 'yes' and 'no' or the device has a mechanism whereby the user can indicate either 'yes' or 'no' (see note below). |
| Keyboard | Device has a numeric keyboard that can input the numbers '0' through '9' and a confirmation. Device also has two buttons that can be easily mapped to 'yes' and 'no' or the device has a mechanism whereby the user can indicate either 'yes' or 'no' (see Note below). |
*Table 1 User Input Capability*
**Note**: 'yes' could be indicated by pressing a button within a certain time limit otherwise 'no' would be assumed.
| Output Capability | Description |
| ----------------- | ----------------------------------------------------------------------------------- |
| No output | Device does not have the ability to display or communicate a 6 digit decimal number |
| Numeric output | Device has the ability to display or communicate a 6 digit decimal number |
*Table 2 User Output Capability*
| | No Output | Numeric Output |
| -------- | -------------------------------------- | --------------------------------- |
| No input | NoInputNoOutput (`ESP_BT_IO_CAP_NONE`) | DisplayOnly (`ESP_BT_IO_CAP_OUT`) |
| Yes / No | NoInputNoOutput (`ESP_BT_IO_CAP_NONE`) | DisplayYesNo (`ESP_BT_IO_CAP_IO`) |
| Keyboard | KeyboardOnly (`ESP_BT_IO_CAP_IN`) | DisplayYesNo (`ESP_BT_IO_CAP_IO`) |
*Table 3 IO Capability Mapping*
## Secure Simple Pairing
The primary goal of Secure Simple Pairing is to simplify the pairing procedure for the user. Secondary goals are to protect against passive eavesdropping and man-in-the-middle (MITM) attacks (active eavesdropping). It uses four association models referred to as Numeric Comparison, Just Works, Out Of Band, and Passkey Entry.
* Numeric Comparison: both devices are capable of displaying a six digit number and both are capable of having the user enter "yes" or "no"
* Just Works: at least one of the devices does not have a display capable of displaying a six digit number nor does it have a keyboard capable of entering six decimal digits
* Out Of Band: use Out of Band mechanism to discover the devices and transfer cryptographic numbers
* Passkey Entry: one device has input capability but does not have the capability to display six digits and the other device has output capabilities.
**Note**: Just Works can be considered as a special kind of Numeric Comparison with automatic accept allowed.
There are four stages defined in the Secure Simple Pairing LM process:
* IO Capability exchange
* Public key exchange
* Authentication stage 1
* Authentication stage 2
### IO Capability Exchange
The IO_Capability_Request_Reply command is used to reply to an IO Capability Request event from the controller, and specifies the current I/O capabilities of the host. The content of this command is shown as Table 4.
| Command | OCF | Command Parameters | Return Parameters |
| ------------------------------- | ------ | ------------------------------------------------------------------------------ | ------------------ |
| HCI_IO_Capability_Request_Reply | 0x002B | BD_ADDR,<br>IO_Capability,<br>OOB_Data_Present,<br>Authentication_Requirements | Status,<br>BD_ADDR |
*Table 4 IO_Capability_Request_Reply command*
### Authentication Requirements
If an authenticated link key is not required by the Host, the Authentication Requirements parameter may be set to one of the following:
* MITM Protection Not Required – No Bonding
* MITM Protection Not Required – Dedicated Bonding
* MITM Protection Not Required – General Bonding
**Note**: If both Hosts set the Authentication_Requirements parameter to one of the above values, the Link Managers shall use the numeric comparison authentication procedure and the hosts shall use the Just Works Association Model.
If an authenticated link key is required by the Host, the Authentication Requirements parameter shall be set to one of the following:
* MITM Protection Required – No Bonding
* MITM Protection Required – Dedicated Bonding
* MITM Protection Required – General Bonding
**Note**: In addition, the following requirements apply:
1. If one or both hosts set the Authentication Requirements parameter to one of the above values, the Link Managers shall use the IO_Capability parameter to determine the authentication procedure.
2. A Host that sets the Authentication_Requirements parameter to one of the above values shall verify that the resulting Link Key type meets the security requirements requested.
### IO Capability and Authentication Procedure Mapping
If one or both devices have set the Authentication_Requirements parameter to one of the MITM Protection Required options, the IO capabilities are mapped to the authentication method as defined in the following table. A host has set the MITM Protection Required options shall verify that the resulting Link Key is an Authenticated Combination Key.
<table>
<tr>
<th ></th>
<th colspan = "4" bgcolor="#1FB0E6">Responder</th>
</tr>
<tr>
<th bgcolor="#C8E6F8">Initiator</th>
<th bgcolor="#1FB0E6">DisplayOnly</th>
<th bgcolor="#1FB0E6">DisplayYesNo</th>
<th bgcolor="#1FB0E6">KeyboardOnly</th>
<th bgcolor="#1FB0E6">NoInputNoOutput</th>
</tr>
<tr>
<th bgcolor="#C8E6F8">DisplayOnly</th>
<td>Just Works<br><br>Unauthenticated</td>
<td>Just Works<br><br>Unauthenticated</td>
<td>Passkey Entry<br><br>Authenticated</td>
<td>Just Works<br><br>Unauthenticated</td>
</tr>
<tr>
<th bgcolor="#C8E6F8">DisplayYesNo</th>
<td>Just Works<br><br>Unauthenticated</td>
<td>Numeric Comparison<br><br>Authenticated</td>
<td>Passkey Entry<br><br>Authenticated</td>
<td>Just Works<br><br>Unauthenticated</td>
</tr>
<tr>
<th bgcolor="#C8E6F8">KeyboardOnly</th>
<td>Passkey Entry<br><br>Authenticated</td>
<td>Passkey Entry<br><br>Authenticated</td>
<td>Passkey Entry(both need enter)<br><br>Authenticated</td>
<td>Just Works<br><br>Unauthenticated</td>
</tr>
<tr>
<th bgcolor="#C8E6F8">NoInputNoOutput</th>
<td>Just Works<br><br>Unauthenticated</td>
<td>Just Works<br><br>Unauthenticated</td>
<td>Just Works<br><br>Unauthenticated</td>
<td>Just Works<br><br>Unauthenticated</td>
</tr>
</table>
*Table 5 IO Capability and Authentication Procedure Mapping*
## Security Mask
Security Mask has two function. First, to decide whether or not required MITM protection for Authentication_Requirements parameter. Second, to set the security level for authentication stage. On ESP32, the Security Masks for A2DP and HFP are hard coded with `BTA_SEC_AUTHENTICATE` and `(BTA_SEC_AUTHENTICATE|BTA_SEC_ENCRYPT)`. The following table shows `sec_mask` value for SPP and its definition in BTA layer of ESP32 Bluetooth stack.
| SPP sec_mask | BTA layer sec_mask | value | Description |
| -------------------------- | ---------------------- | ------ | ----------------------------------------------------------------------------------------- |
| `ESP_SPP_SEC_NONE` | `BTA_SEC_NONE` | 0x0000 | No security |
| `ESP_SPP_SEC_AUTHORIZE` | `BTA_SEC_AUTHORIZE` | 0x0001 | Authorization required (only needed for out going connection)<br>(not support) |
| `ESP_SPP_SEC_AUTHENTICATE` | `BTA_SEC_AUTHENTICATE` | 0x0012 | Authentication required |
| `ESP_SPP_SEC_ENCRYPT` | `BTA_SEC_ENCRYPT` | 0x0024 | Encryption required |
| `ESP_SPP_SEC_MODE4_LEVEL4` | `BTA_SEC_MODE4_LEVEL4` | 0x0040 | Mode 4 level 4 service, i.e. incoming/outgoing MITM and P-256 encryption<br>(not support) |
| `ESP_SPP_SEC_MITM` | `BTA_SEC_MITM` | 0x3000 | Man-In-The_Middle protection |
| `ESP_SPP_SEC_IN_16_DIGITS` | `BTA_SEC_IN_16_DIGITS` | 0x4000 | Min 16 digit for pin code |
*Table 6 ESP32 SPP Security Mask*
**Note**:
1. When `ESP_SPP_SEC_AUTHENTICATE` is set, then Security Manager set `ESP_SPP_SEC_MITM` automatically.
2. When `ESP_SPP_SEC_ENCRYPT` is set, then Security Manager set `ESP_SPP_SEC_AUTHENTICATE` automatically.
## Security Mode 4
The ESP32 Security Manager supports Security Mode 4 which means that it enforces security requirements before it attempts to access services offered by a remote device and before it grants access to services it offers to remote devices. Security Mode 4 has 4 level of security.
<table>
<tr>
<th width='200'>Security Level Required for Service</th>
<th>Link Key type required for remote devices</th>
<th width='200'>Comments</th>
<th width='200'>IO Capability & Security Mask Setting</th>
</tr>
<tr>
<td><b>Level 4(not support)</b><br>* MITM protection required<br>* Encryption required<br>* User interaction acceptable</td>
<td>Authenticated (P-256 based Secure Simple Pairing and Secure Authentication)</td>
<td>Highest Security Only possible when both devices support Secure Connections</td>
<td>/</td>
</tr>
<tr>
<td><b>Level 3</b><br>* MITM protection required<br>* Encryption required<br>* User interaction acceptable</td>
<td>Authenticated</td>
<td>High Security</td>
<td>IO: >= DisplayYesNo <br>Mask: ESP_SPP_SEC_MITM | BTA_SEC_ENCRYPT</td>
</tr>
<tr>
<td><b>Level 2</b><br>* MITM protection not necessary<br>* Encryption desired</td>
<td>Unauthenticated</td>
<td>Medium Security</td>
<td>IO: >= DisplayYesNo <br>Mask: BTA_SEC_ENCRYPT</td>
</tr>
<tr>
<td><b>Level 1</b><br>* MITM protection not necessary<br>* Encryption desired<br>* Minimal user interaction desired</td>
<td>Unauthenticated</td>
<td>Low Security</td>
<td>IO: >= NoInputNoOutput <br>Mask: BTA_SEC_ENCRYPT</td>
</tr>
<tr>
<td><b>Level 0</b><br>* MITM protection not necessary<br>* Encryption not necessary<br>* No user interaction desired</td>
<td>None</td>
<td>Permitted only for SDP and service data sent via either L2CAP fixed signaling channels or the L2CAP connectionless channel to PSMs that correspond to service class UUIDs which are allowed to utilize Level 0.</td>
<td>/</td>
</tr>
</table>
*Table 7 Security Mode 4 Security Level mapping to link key requirements*
**Note**: Security Mode 4 always requires **authentication** and **encryption** over establishment of L2CAP connection on ESP32.
ESP32 Secure Simple Pairing performs legacy authentication which means mutual authentication is achieved by first performing the authentication procedure in one direction and then immediately performing the authentication procedure in the opposite direction. So, when the initiator does not require MITM protection, the generated link key type in this direction is unauthenticated. In other direction, if the responder need MITM protection and have the `sec_mask` of `ESP_SPP_SEC_AUTHENTICATE`, then the unauthenticated link key will be regenerated and upgraded to an authenticated one. Each time the link key is regenerated, user will receive a `ESP_BT_GAP_AUTH_CMPL_EVT` event.

52
examples/bluetooth/bluedroid/classic_bt/bt_spp_acceptor/README.md Normal file
View File

@ -0,0 +1,52 @@
| Supported Targets | ESP32 |
| ----------------- | ----- |
## ESP-IDF BT-SPP-ACCEPTOR demo
This is the demo for user to use ESP_APIs to create a **Serial Port Protocol** (**SPP**) acceptor and we aggregate **Secure Simple Pair** (**SSP**) into this demo to show how to use SPP when creating your own APPs.
## How to use example
### Hardware Required
This example is designed to run on commonly available ESP32 development board, e.g. ESP32-DevKitC.
To operate it should be connected to an SPP Initiator running on a smartphone or on another ESP32 development board.
### Configure the project
```
idf.py menuconfig
```
In `menuconfig` path: `Coponent config --> Bluetooth--> Bluedroid Options --> SPP` and `Coponent config --> Bluetooth--> Bluedroid Options --> Secure Simple Pair`.
### Build and Flash
Build the project and flash it to the board, then run monitor tool to view serial output:
```
idf.py -p PORT flash monitor
```
(Replace PORT with the name of the serial port to use.)
(To exit the serial monitor, type ``Ctrl-]``.)
See the [Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html) for full steps to configure and use ESP-IDF to build projects.
## Example Description
After the program started, `bt_spp_initator` will connect it and send data.
## Trouble shooting
- Acceptor is expected to start before `bt_spp_initator` start.
- To see the information of data, users shall set `SPP_SHOW_MODE` as `SPP_SHOW_DATA` or `SPP_SHOW_SPEED` in code(should be same with `bt_spp_initator`).
- We also show the Security Simple Pair in this SPP demo. Users can set the IO Capability and Security Mode for their device (security level is fixed level 4). The default security mode of this demo is `ESP_SPP_SEC_AUTHENTICATE` which support MITM (Man In The Middle) protection. For more information about Security Simple Pair on ESP32, please refer to [ESP32_SSP](./ESP32_SSP.md).
## FAQ
Q: How many SPP servers does ESP32 support?
A: For now, the maximum number of SPP servers is 6, which is limited by the maximum number of SDP records. When the SPP server is successfully started, the unique SCN (Server Channel Number) will be mapped to the SPP server.

20
examples/bluetooth/bluedroid/classic_bt/bt_spp_acceptor/README.rst
View File

@ -1,20 +0,0 @@
================= =====
Supported Targets ESP32
================= =====
ESP-IDF BT-SPP-ACCEPTOR demo
======================
Demo of SPP acceptor role
This is the demo for user to use ESP_APIs to create a SPP acceptor.
Options choose step:
1. idf.py menuconfig.
2. enter menuconfig "Component config", choose "Bluetooth"
3. enter menu Bluetooth, choose "Classic Bluetooth" and "SPP Profile"
4. choose your options.
Then set SPP_SHOW_MODE as SPP_SHOW_DATA or SPP_SHOW_SPEED in code(should be same with bt_spp_initator).
After the program started, bt_spp_initator will connect it and send data.

54
examples/bluetooth/bluedroid/classic_bt/bt_spp_initiator/README.md Normal file
View File

@ -0,0 +1,54 @@
| Supported Targets | ESP32 |
| ----------------- | ----- |
# ESP-IDF BT-SPP-INITATOR demo
This is the demo for user to use ESP_APIs to create a **Serial Port Protocol** (**SPP**) initiator and we aggregate **Secure Simple Pair** (**SSP**) into this demo to show how to use SPP when creating your own APPs.
## How to use example
### Hardware Required
This example is designed to run on commonly available ESP32 development board, e.g. ESP32-DevKitC. To operate it should be connected to an SPP Acceptor running on another device.
### Configure the project
```
idf.py menuconfig
```
In `menuconfig` path: `Coponent config --> Bluetooth--> Bluedroid Options --> SPP` and `Coponent config --> Bluetooth--> Bluedroid Options --> Secure Simple Pair`.
### Build and Flash
Build the project and flash it to the board, then run monitor tool to view serial output:
```
idf.py -p PORT flash monitor
```
(Replace PORT with the name of the serial port to use.)
(To exit the serial monitor, type ``Ctrl-]``.)
See the [Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html) for full steps to configure and use ESP-IDF to build projects.
## Troubleshouting
- Set `SPP_SHOW_MODE` as `SPP_SHOW_DATA` or `SPP_SHOW_SPEED` in code (should be same with bt_spp_acceptor).
- After the program started, It will connect to bt_spp_acceptor and send data.
- We haven't do the same update to `bt_acceptor_demo` for the sake of reducing the size of ESP_IDF, but transplanting of input module is supported.
- We also show the Security Simple Pair in this SPP demo. Users can set the IO Capability and Security Mode for their device (security level is fixed level 4). The default security mode of this demo is `ESP_SPP_SEC_AUTHENTICATE` which support MITM (Man In The Middle) protection. For more information about Security Simple Pair on ESP32, please refer to [ESP32_SSP](../bt_spp_acceptor/ESP32_SSP.md).
## FAQ
Q: How can we reach the maximum throughput when using SPP?
A: The default MTU size of classic Bluetooth SPP on ESP32 is 990 bytes, and higher throughput can be achieved in the case that data chunck size is close to the MTU size or multiple of MTU size. For example, sending 100 bytes data per second is much better than sending 10 bytes every 100 milliseconds.
Q: What is the difference between the event `ESP_SPP_CONG_EVT` and the parameter `cong` of the event `ESP_SPP_WRITE_EVT`?
A: The event `ESP_SPP_CONG_EVT` shows the changing status from `congest` to `uncongest`, or form `uncongest` to `congest`. Congestion can have many causes, such as using out of the credit which is sent by peer, reaching the high watermark of the Tx buffer, the congestion at Bluetooth L2CAP layer and so on. The parameter `cong` of the event `ESP_SPP_WRITE_EVT` shows a snapshot of the state of the flow control manager after the write operation is completed. The user needs to carefully consider retransmitting or continuing to write according to these two events. The ESP32 offers an VFS mode of SPP which hides the details of retransmitting, but it will block the caller and is not more efficient than the callback mode.
Q: How many SPP clients does ESP32 support?
A: The ESP32 supports maximum 8 SPP clients, which including virtual SPP connections. Virtual SPP connection means that SPP clients can connect to the different SPP servers running on the same peer device. However the number of SPP clients (excluding virtual connections) shall not exceed the number of Bluetooth ACL connections.

20
examples/bluetooth/bluedroid/classic_bt/bt_spp_initiator/README.rst
View File

@ -1,20 +0,0 @@
================= =====
Supported Targets ESP32
================= =====
ESP-IDF BT-SPP-INITATOR demo
======================
Demo of SPP initator role
This is the demo for user to use ESP_APIs to create a SPP initator.
Options choose step:
1. idf.py menuconfig.
2. enter menuconfig "Component config", choose "Bluetooth"
3. enter menu Bluetooth, choose "Classic Bluetooth" and "SPP Profile"
4. choose your options.
Then set SPP_SHOW_MODE as SPP_SHOW_DATA or SPP_SHOW_SPEED in code(should be same with bt_spp_acceptor).
After the program started, It will connect to bt_spp_acceptor and send data.