Gatt Security Server Example Walkthrough

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 and implemented on the ESP-IDF BLE stack, specifically on the Security Manager Protocol (SMP) API.

BLE security involves three interrelated concepts: pairing, bonding and encryption. Pairing concerns with the exchange of security features and types of keys needed. In addition, the pairing procedure takes care of the generation and exchange of shared keys. The core specification defines the legacy pairing and Secure Connections pairing (introduced in Bluetooth 4.2), which are both supported by ESP32. Once the exchange of shared keys is completed, a temporary encrypted link is established to exchange short term and long term keys. Bonding refers to storing the exchanged keys for subsequent connections so that they do not have to be transmitted again. Finally, encryption pertains to the ciphering of plain text data using the AES-128 engine and the shared keys. Server attributes may also be defined to allow only encrypted write and read messages. At any point of the communication, a slave device can always ask to start encryption by issuing a security request to the other peer device, which returns a security response by calling an API.

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 [Vol 3, Part H].

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 [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:

IO Capability: describes if the device has input/output capabilities such as a display or a keyboard.
OOB Flag: describes if the device supports Out of Band passkey exchange, for example using NFC or Wi-Fi to exchange keys as TKs.
Authorization Request: indicates the requested security properties such as Bonding, Secure Connections (SC), MITM protection or none that will be present in the Pairing Request and Response packets.
Maximum Encryption Key Size: maximum encryption key size in octets.
Initiator Key Distribution/Generation: indicates which keys the initiator is requesting to distribute/generate or use during the Transport Specific Key Distribution phase. In the pairing request, these keys are requested, while in the pairing response, these keys are confirmed to be distributed.
Responder Key Distribution/Generation: indicates which keys the initiator is requesting the responder to distribute/generate or use during the Transport Specific Key Distribution phase. In the pairing request, these keys are requested, while in the pairing response, these keys are confirmed to be distributed.

In code, these parameters are defined as follows:

IO Capability:

 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:

 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:

 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:

 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:

 uint8_t key_size = 16;      //the key size should be 7~16 bytes

Initiator Key Distribution/Generation:
```
 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.

Responder Key Distribution/Generation:

 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.

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:

 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

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.

case ESP_GATTS_CONNECT_EVT:
     //start security connect with peer device when receive the connect event sent by the master.  
    esp_ble_set_encryption(param->connect.remote_bda, ESP_BLE_SEC_ENCRYPT_MITM);  
    break;

The types of encryptions available are:

ESP_BLE_SEC_NONE
ESP_BLE_SEC_ENCRYPT
ESP_BLE_SEC_ENCRYPT_NO_MITM
ESP_BLE_SEC_ENCRYPT_MITM

The difference between ESP_BLE_SEC_ENCRYPT and ESP_BLE_SEC_ENCRYPT_NO_MITM lies in the fact that a previous connection might have a security level that needs to be upgraded, therefore requires to exchange keys again.

In this example, the I/O capabilities are set to No Input No Output, therefore the Just Works pairing method, which doesn't not require the generation of a random 6-digit passkey, is used (For details, please refer to the the table below). The user may modify the example to set the I/O capabilities to use other than No Input No Output. Therefore, depending on the I/O capabilities of the remote device, a passkey might be generated on the ESP32 which is presented to the user with the ESP_GAP_BLE_PASSKEY_NOTIF_EVT:

case ESP_GAP_BLE_PASSKEY_NOTIF_EVT:    
     ///the app will receive this evt when the IO  has Output capability and the peer device IO has Input capability.
     ///show the passkey number to the user to input it in the peer device.
     ESP_LOGE(GATTS_TABLE_TAG, "The passkey Notify number:%d", param->ble_security.key_notif.passkey);
     break;

The combination of input and output capabilities that determine which algorithm is used are:

	Display Only	Display Yes/No	Keyboard Only	No Input No Output	Keyboard Display
Display Only	Just Works	Just Works	Passkey Entry	Just Works	Passkey Entry
Display Yes/No	Just Works	Just Works	Passkey Entry	Just Works	Passkey Entry
Keyboard Only	Passkey Entry	Passkey Entry	Passkey Entry	Just Works	Passkey Entry
No Input No Output	Just Works	Just Works	Just Works	Just Works	Just Works
Keyboard Display	Passkey Entry	Passkey Entry	Passkey Entry	Just Works	Passkey Entry

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:

Local device LTK
Local device IRK
Local device CSRK
Peer device LTK
Peer device IRK

Note that for this example only, the peer device CSRK is not exchanged. For each key exchange message, an ESP_GAP_BLE_KEY_EVT event is triggered, which can be used to print the type of key received:

case ESP_GAP_BLE_KEY_EVT:
     //shows the ble key info share with peer device to the user.
     ESP_LOGI(GATTS_TABLE_TAG, "key type = %s", esp_key_type_to_str(param->ble_security.ble_key.key_type));
     break;

When the keys are exchanged successfully, the pairing process is done. This triggers an ESP_GAP_BLE_AUTH_CMPL_EVT event, which is used to print information such as remote device, address type and pair status:

case ESP_GAP_BLE_AUTH_CMPL_EVT: {
     esp_bd_addr_t bd_addr;
     memcpy(bd_addr, param->ble_security.auth_cmpl.bd_addr,  
            sizeof(esp_bd_addr_t));
     ESP_LOGI(GATTS_TABLE_TAG, "remote BD_ADDR: %08x%04x",\
              (bd_addr[0] << 24) + (bd_addr[1] << 16) + (bd_addr[2] << 8) +   
              bd_addr[3],  
              (bd_addr[4] << 8) + bd_addr[5]);
     ESP_LOGI(GATTS_TABLE_TAG, "address type = %d",   
              param->ble_security.auth_cmpl.addr_type);  
              ESP_LOGI(GATTS_TABLE_TAG, "pair status = %s",  
              param->ble_security.auth_cmpl.success ? "success" : "fail");
     break;
}

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:

Permission to read
Permission to read with encryption
Permission to read with encryption and MITM protection
Permission to write
Permission to write with encryption
Permission to write with encryption and MITM protection
Permission to signed write
Permission to signed write with MITM protection

These permissions are defined in the API as:

ESP_GATT_PERM_READ
ESP_GATT_PERM_READ_ENCRYPTED
ESP_GATT_PERM_READ_ENC_MITM
ESP_GATT_PERM_WRITE
ESP_GATT_PERM_WRITE_ENCRYPTED
ESP_GATT_PERM_WRITE_ENC_MITM
ESP_GATT_PERM_WRITE_SIGNED
ESP_GATT_PERM_WRITE_SIGNED_MITM

When creating the services table, each attribute can have permissions to read or write, with or without encryption. When an attribute has encrypted permissions and a peer device that does not have the required security clearance tries to read or write to that attribute, the local host sends an Insufficient Authorization Error. In the example, the following attributes are defined with permissions with encryption:

…
// Body Sensor Location Characteristic Value
    [HRS_IDX_BOBY_SENSOR_LOC_VAL]   = {
    {ESP_GATT_AUTO_RSP},  
    {ESP_UUID_LEN_16,  
    (uint8_t *)&body_sensor_location_uuid,
    ESP_GATT_PERM_READ_ENCRYPTED,
    sizeof(uint8_t),  
    sizeof(body_sensor_loc_val),  
    (uint8_t *)body_sensor_loc_val}
    },
…
// Heart Rate Control Point Characteristic Value
    [HRS_IDX_HR_CTNL_PT_VAL]        = {
    {ESP_GATT_AUTO_RSP},  
    {ESP_UUID_LEN_16,  
    (uint8_t *)&heart_rate_ctrl_point,  
    ESP_GATT_PERM_WRITE_ENCRYPTED|ESP_GATT_PERM_READ_ENCRYPTED,  
    sizeof(uint8_t),  
    sizeof(heart_ctrl_point),   
    (uint8_t *)heart_ctrl_point}  
    },
…

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.

case ESP_GAP_BLE_SEC_REQ_EVT:
     /* send the positive (true) security response to the peer device to accept the security request.
     If not accept the security request, should send the security response with negative(false) accept value*/
     esp_ble_gap_security_rsp(param->ble_security.ble_req.bd_addr, true);
     break;

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Gatt_Security_Server_Example_Walkthrough.md

Gatt_Security_Server_Example_Walkthrough.md

Gatt Security Server Example Walkthrough

Introduction

Setting Security Parameters

Connecting and Bonding to a Peer Device

Exchanging Keys

Security Permission for Attributes

Security Requests

Conclusion

Files

Gatt_Security_Server_Example_Walkthrough.md

Latest commit

History

Gatt_Security_Server_Example_Walkthrough.md

File metadata and controls

Gatt Security Server Example Walkthrough

Introduction

Setting Security Parameters

Connecting and Bonding to a Peer Device

Exchanging Keys

Security Permission for Attributes

Security Requests

Conclusion