pioduino/esp-idf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

component/bt: Modify docs to be compatible with "Github Standard Markdown"

Browse Source
This commit is contained in:
island
2018-01-03 11:07:55 +08:00
parent 85efc08c27
commit 5c82ef1034
5 changed files with 127 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files
examples/bluetooth/gatt_security_server/tutorial/GATT_SECURITY_SERVER_EXAMPLE_WALKTHROUGH.md
+50 -50
View File
@@ -1,6 +1,6 @@
#GATT SECURITY SERVER EXAMPLE WALKTHROUGH
# Gatt Security Server Example Walkthrough
##INTRODUCTION
## Introduction
In this document, a description of the security GATT Server BLE example for the ESP32 is presented. The security configuration enables a GATT Server acting as a slave device to bond with a master and establish an encrypted link between them. This functionality is defined by the [Bluetooth Specification version 4.2](https://www.bluetooth.com/specifications/bluetooth-core-specification) and implemented on the ESP-IDF BLE stack, specifically on the Security Manager Protocol (SMP) API.
@@ -8,7 +8,7 @@ BLE security involves three interrelated concepts: pairing, bonding and encrypti
This document only describes the security configuration. The rest of the GATT server functionalities, such as defining the service table, are explained in the GATT Server example walkthrough documentation. For a better understanding of this example workflow, it is recommended that the reader is familiar with the pairing feature exchange and key generation defined in the section 3.5 of the [Bluetooth Specification Version 4.2](https://www.bluetooth.com/specifications/bluetooth-core-specification) [Vol 3, Part H].
##SETTING SECURITY PARAMETERS
## Setting Security Parameters
The ESP32 requires a series of security parameters in order to define how the pairing request and response are going to be built. The Pairing Response packet built by the GATT Server includes fields such as the input/output capabilities, Secure Connections pairing, authenticated Man-In-The-Middle (MITM) protection or no security requirements (see Section 2.3.1 of the [Bluetooth Specification Version 4.2](https://www.bluetooth.com/specifications/bluetooth-core-specification) [Vol 3, Part H]). In this example, this procedure is done in the `app_main()` function. The pairing request is sent by the initiator which in this case is a remote GATT client. The ESP32 server implemented in this example receives this request and replies with a pairing response, which contains the same security parameters in order for both devices to agree on the resources available and the applicable pairing algorithm (*Just Works* or *Passkey Entry*). Both the pairing request and response commands have the following parameters:
@@ -23,74 +23,74 @@ In code, these parameters are defined as follows:
* *IO Capability*:
```c
esp_ble_io_cap_t iocap = ESP_IO_CAP_NONE;//set the IO capability to No Input No Output
```
```c
esp_ble_io_cap_t iocap = ESP_IO_CAP_NONE;//set the IO capability to No Input No Output
```
The possible values for *IO Capabilities* are:
The possible values for *IO Capabilities* are:
```c
ESP_IO_CAP_OUT 0 /*!< DisplayOnly */
ESP_IO_CAP_IO 1 /*!< DisplayYesNo */
ESP_IO_CAP_IN 2 /*!< KeyboardOnly */
ESP_IO_CAP_NONE 3 /*!< NoInputNoOutput */
ESP_IO_CAP_KBDISP 4 /*!< Keyboard display */
```
```c
ESP_IO_CAP_OUT 0 /*!< DisplayOnly */
ESP_IO_CAP_IO 1 /*!< DisplayYesNo */
ESP_IO_CAP_IN 2 /*!< KeyboardOnly */
ESP_IO_CAP_NONE 3 /*!< NoInputNoOutput */
ESP_IO_CAP_KBDISP 4 /*!< Keyboard display */
```
* *Authorization Request*:
```c
esp_ble_auth_req_t auth_req = ESP_LE_AUTH_BOND;
```c
esp_ble_auth_req_t auth_req = ESP_LE_AUTH_BOND;
//bonding with peer device after authentication
```
```
The possible values for *Authorization Request* are a combination of Bonding, MITM protection and Secure Connections requests:
The possible values for *Authorization Request* are a combination of Bonding, MITM protection and Secure Connections requests:
```c
ESP_LE_AUTH_NO_BOND: No bonding.
ESP_LE_AUTH_BOND: Bonding is performed.
ESP_LE_AUTH_REQ_MITM: MITM Protection is enabled.
ESP_LE_AUTH_REQ_SC_ONLY: Secure Connections without bonding enabled.
ESP_LE_AUTH_REQ_SC_BOND: Secure Connections with bonding enabled.
ESP_LE_AUTH_REQ_SC_MITM: Secure Connections with MITM Protection and no bonding enabled.
ESP_LE_AUTH_REQ_SC_MITM_BOND: Secure Connections with MITM Protection and bonding enabled.
```
```c
ESP_LE_AUTH_NO_BOND: No bonding.
ESP_LE_AUTH_BOND: Bonding is performed.
ESP_LE_AUTH_REQ_MITM: MITM Protection is enabled.
ESP_LE_AUTH_REQ_SC_ONLY: Secure Connections without bonding enabled.
ESP_LE_AUTH_REQ_SC_BOND: Secure Connections with bonding enabled.
ESP_LE_AUTH_REQ_SC_MITM: Secure Connections with MITM Protection and no bonding enabled.
ESP_LE_AUTH_REQ_SC_MITM_BOND: Secure Connections with MITM Protection and bonding enabled.
```
* *Maximum Encryption Key Size*:
```c
uint8_t key_size = 16; //the key size should be 7~16 bytes
```
```c
uint8_t key_size = 16; //the key size should be 7~16 bytes
```
* *Initiator Key Distribution/Generation*:
```c
uint8_t init_key = ESP_BLE_ENC_KEY_MASK | ESP_BLE_ID_KEY_MASK;
```
```c
uint8_t init_key = ESP_BLE_ENC_KEY_MASK | ESP_BLE_ID_KEY_MASK;
```
The initiator distributes the LTK and IRK keys by the setting the EncKey and IdKey masks.
The initiator distributes the LTK and IRK keys by the setting the EncKey and IdKey masks.
* *Responder Key Distribution/Generation*:
```c
uint8_t rsp_key = ESP_BLE_ENC_KEY_MASK | ESP_BLE_ID_KEY_MASK;
```c
uint8_t rsp_key = ESP_BLE_ENC_KEY_MASK | ESP_BLE_ID_KEY_MASK;
```
The responder distributes the LTK and IRK keys by the setting the *EncKey* and *IdKey* masks.
The responder distributes the LTK and IRK keys by the setting the *EncKey* and *IdKey* masks.
Once defined, the parameters are set using the `esp_ble_gap_set_security_param()` function. This function sets the parameter type, the parameter value and the parameter length:
Once defined, the parameters are set using the `esp_ble_gap_set_security_param()` function. This function sets the parameter type, the parameter value and the parameter length:
```c
esp_ble_gap_set_security_param(ESP_BLE_SM_AUTHEN_REQ_MODE, &auth_req, sizeof(uint8_t));
esp_ble_gap_set_security_param(ESP_BLE_SM_IOCAP_MODE, &iocap, sizeof(uint8_t));
esp_ble_gap_set_security_param(ESP_BLE_SM_MAX_KEY_SIZE, &key_size, sizeof(uint8_t));
esp_ble_gap_set_security_param(ESP_BLE_SM_SET_INIT_KEY, &init_key, sizeof(uint8_t));
esp_ble_gap_set_security_param(ESP_BLE_SM_SET_RSP_KEY, &rsp_key, sizeof(uint8_t));
```
```c
esp_ble_gap_set_security_param(ESP_BLE_SM_AUTHEN_REQ_MODE, &auth_req, sizeof(uint8_t));
esp_ble_gap_set_security_param(ESP_BLE_SM_IOCAP_MODE, &iocap, sizeof(uint8_t));
esp_ble_gap_set_security_param(ESP_BLE_SM_MAX_KEY_SIZE, &key_size, sizeof(uint8_t));
esp_ble_gap_set_security_param(ESP_BLE_SM_SET_INIT_KEY, &init_key, sizeof(uint8_t));
esp_ble_gap_set_security_param(ESP_BLE_SM_SET_RSP_KEY, &rsp_key, sizeof(uint8_t));
```
This information is enough for the BLE stack to perform the pairing process, including pairing confirmation and key generation. The procedure is invisible to the user and executed automatically by the stack.
##CONNECTING AND BONDING TO A PEER DEVICE
## Connecting and Bonding to a Peer Device
The security parameters set previously are stored locally to be used later when the master device connects to the slave. Every time a remote device connects to the local GATT server, the connection event `ESP_GATTS_CONNECT_EVT` is triggered. This event is employed to perform the pairing and bonding process by invoking the `esp_ble_set_encryption()` function which takes as parameters the remote device address and the type of encryption that will be performed. The BLE stack then executes the actual pairing process in the background. In this example, the encryption includes MITM protection.
@@ -122,7 +122,7 @@ case ESP_GAP_BLE_PASSKEY_NOTIF_EVT:
The combination of input and output capabilities that determine which algorithm is used are:
##EXCHANGING KEYS
## Exchanging Keys
When the client connects to the server and the pairing is done successfully, the keys indicated by the `init_key` and `rsp_key` security parameters are exchanged. In this example the following keys are generated and distributed:
@@ -160,7 +160,7 @@ case ESP_GAP_BLE_AUTH_CMPL_EVT: {
}
```
##SECURITY PERMISSIONS FOR ATTRIBUTES
## Security Permission for Attributes
When defining the attributes of the server, different permissions can be set to the write and read events. Attributes permissions can be:
@@ -212,7 +212,7 @@ When creating the services table, each attribute can have permissions to read or
…
```
##SECURITY REQUESTS
## Security Requests
During the communication between a master and a slave device, the slave might request to start encryption at any moment by issuing a security request command. This command will trigger an `ESP_GAP_BLE_SEC_REQ_EVT` event on the master, which will reply a positive (true) security response to the peer device to accept the request or a negative (false) one to reject the request. In this example, this event is used to reply a start encryption response by using the `esp_ble_gap_security_rsp()` API call.
@@ -223,7 +223,7 @@ During the communication between a master and a slave device, the slave might re
esp_ble_gap_security_rsp(param->ble_security.ble_req.bd_addr, true);
break;
```
##CONCLUSION
## Conclusion
In this document, a review of the security aspects of the GATT Server has been realized. BLE security encompasses Pairing, Bonding and Encryption. In order to establish a secured link between a master and a slave device, security parameters that define the capabilities and features each device possess are set. The combination of features and capabilities of the peer devices results in the selection of the appropriate pairing method which the BLE stack then executes. Immediately, the required keys are generated and exchanged, and the encryption of subsequent messages is started using the AES-128 engine and these keys. These steps trigger different events that are managed by the GATT and GAP event handlers which can be used to print useful information such as the types of keys exchanged and the pairing status. In addition, attribute permissions are appointed to allow only encrypted read and write events when needed. The rest of the Security GATT server functionalities such as defining services and characteristics are implemented in the same way as presented in the GATT Server example.