1. Bluetooth® Low Energy security overview
This article provides a basic understanding of Bluetooth® Low Energy security features. It explains the different security features, how to setup these features on STM32WB0, how to decrypt the traffic using a sniffer and additional information regarding Bluetooth® Low Energy characteristics and security permissions.
1.1. Security features
| Bluetooth® Low Energy secure link |
|---|
 |
The Bluetooth® Low Energy security model includes five distinct security features:
- Pairing: process for creating one or more shared secret keys
- Bonding: the act of storing the keys created during pairing for use in subsequent connections in order to form a trusted device pair
- Device authentication: verification that the two devices have the same keys
- Encryption: message confidentiality
- Message integrity: protects against message forgeries (4 bytes Message Integrity Check MIC)
Refer to Bluetooth®LE Security Study Guide [1].
1.2. Pairing process
Pairing provides each device with security resources, such as keys, which are needed to allow other security features, such as encryption, to be used. If two devices have not paired, they are unable to encrypt the link and unable to sign data. Therefore, pairing is performed to establish keys which can then be used to encrypt a link.
Bluetooth® Low Energy uses 2 pairing methods:
- LE legacy pairing : Introduced in Bluetooth® Low Energy standard v4.0 and v4.1 and based on AES-CCM encryption
- LE secure connection : Introduced in Bluetooth® Low Energy standard v4.2 which upgrades LE legacy pairing to utilize FIPS-approved algorithms (AES-CMAC and P-256 elliptic curve) on the LE physical transport
The pairing is composed of three phases:
- Phase 1: Pairing feature exchange
- Phase 2: Key generation method selection
- LE legacy pairing: Short term key (STK) generation
- LE secure connections: Long term key (LTK) generation
- Phase 3: Transport specific key distribution
| Pairing flowchart which applies to both legacy pairing and secure connections |
|---|
 |
1.2.1. Phase 1: Pairing feature exchange
The pairing feature exchange phase is used to exchange device capabilities to the peer device and vice versa. The information exchange are the security features that include, for example, Input/Output (IO) capabilities, requirements for Man-In-The-Middle (MIMT) protection, OOB authentication data availability, authentication requirements, and key size. The exchange of pairing information between two devices is done through the pairing request and pairing response packet and determines the key generation method used in phase 2.
Note: All data being exchanged during this phase is unencrypted.
| Pairing Feature Exchange |
|---|
 |
1.2.2. Phase 2: Key generation method selection
The key generation phase is specific for each pairing method. According to the capabilities exchange in phase 1, the key generation method is one of the following methods for Bluetooth® LE legacy pairing and Bluetooth LE secure connection:
Bluetooth® LE legacy pairing:
- Just Works
- Passkey Entry
- Out of Band (OOB)
Bluetooth® LE secure connection includes the three methods above and adds one new one:
- Numeric Comparison
The key generation methods depend on authentication requirements, availability of OOB data and IO capabilities.
The following sequence of rules are followed to determine the type of pairing (LE legacy or LE secure connections) used and the key generation method.
- If LE secure connections pairing is supported by both devices, use the LE secure connections pairing, otherwise use LE legacy pairing.
- If LE legacy pairing is used and both devices have Out of Band authentication data, use the OOB pairing method.
- If LE secure connections pairing is used and at least one of the devices has Out of Band authentication data, use the OOB pairing method.
- If both devices have not requested the MITM protection requirement, use the Just Works method.
- Otherwise, use the IO Capabilities to select the key generation method, according to the table below.
| Mapping of IO capabilities to key generation method |
|---|
 |
In the table above:
- Authenticated means MITM (Man-In-The-Middle) protection is required.
- Unauthenticated means MITM (Man-In-The-Middle) protection is not required.
1.2.2.1. LE legacy pairing - Short term key (STK) generation
For LE legacy pairing, phase 2 is called short term key (STK) generation. This method uses and generates 2 keys:
1. Temporary key (TK): a 128-bit temporary key used in the pairing process used to generate STK
2. Short term key (STK): a 128-bit temporary key used to encrypt a connection following pairing
The diagram below describes each step of the short term key (STK) generation:
| Short Term Key (STK) Generation |
|---|
 |
As shown in the diagram above, the temporary key (TK) is set to different values depending on the key generation method used:
- Just Works: TK is set to 0
- Passkey Entry: TK is equal to passkey + 0 padded (MSB)
- OOB: TK is equal to OOB data
1.2.2.2. LE secure connections : Long term key (LTK) generation
For LE secure connections, phase 2 is called long term key (LTK) generation. This method uses and generates one key:
- Long term key (LTK): a 128-bit key used to encrypt the connection following pairing and subsequent connections
When LE secure connections is used, the long term key (LTK) generation is split in four steps:
- Step 1 : Public key exchange
- Step 2 : Secure connections key (LTK) generation - authentication stage 1 : Specific for each key generation method
- Step 3 : Long term key (LTK) calculation
- Step 4 : DHKey checks - authentication stage 2
The diagram below describes each step of the long term key (LTK) generation when Just Works or Numeric Comparison method is used:
| Long Term Key (LTK) Generation for Just Works and Numeric Comparison method |
|---|
 |
Note: The sequence for Just Works is identical to that of Numeric Comparison with the exception that the host does not show the numbers to the user.
The diagram below describes each step of the long term key (LTK) generation when the Passkey Entry method is used:
| Long Term Key (LTK) Generation for Passkey Entry method |
|---|
 |
Note: Passkey Entry may prolong the pairing experience because of the time required to execute 20 repetitions over SMP.
The diagram below describes each step of the long term key (LTK) generation when the OOB method is used:
| Long Term Key (LTK) Generation for Out Of Band method |
|---|
 |
1.2.3. Phase 3: Transport specific key distribution
After the key generation, the link is encrypted and the transport specific keys are distributed. The following diagram shows an example of all keys and values being distributed by central and peripheral:
| Transport Specific Key Distribution |
|---|
 |
LTK, EDIV, and Rand may be distributed only when legacy pairing is used.
1.3. Bonding
If the security resources provided by pairing are stored for future reuse by the paired devices, they are said to be bonded.
1.4. Device authentication
Authentication is concerned with obtaining proof that device communication is really between the correct devices and not some other, imposter device. Sometimes, device authentication takes the idea further and verifies the identity of the person using the device.
1.5. Encryption
Encryption encodes information so that an unauthorized third party coming into possession of the encoded information cannot decode it and access the original information. Encryption addresses the need for confidentiality by ensuring sensitive information can be transmitted in the presence of eavesdroppers without them being able to access it while allowing the intended recipient of the data to decode it.
1.6. Message integrity
There are a number of ways in which transmitted data could change as it is being communicated from one device to another. It could become corrupted as a consequence of interference. Or it could be deliberately tampered with, changing its value in some way that is advantageous to an attacker. Ensuring changes to transmitted data cannot occur without being detected is what integrity is all about. It is also about ensuring data can be trusted and about making sure data corruption is detected and dealt with.
1.7. LE security mode
The security requirements of a device, a service, or a service request are expressed in terms of a security mode and security level. Each service or service request may have its own security requirement. The device may also have a security requirement. A physical connection between two devices operates in only one security mode.
STM32WB0 supports the LE security mode 1, which has the following security levels:
- Level 1 - No security (No authentication and no encryption). This means that devices are connected without any security measures against malicious devices.
- Level 2 - Unauthenticated pairing with encryption (no MITM protection)
- Level 3 - Authenticated pairing with encryption (MITM protection)
- Level 4 - Authenticated LE secure connections pairing with encryption using a 128-bit strength encryption key
2. How to setup the pairing with STM32WB0 application
2.1. Parameters and commands overview
The following commands are used during the initialization of the device (that is, when the device is not in connected state):
- aci_gap_set_io_capability : Sets the IO capabilities of the device. To successfully pair with a device, IO capabilities must be correctly configured, depending on the real IO capability available locally on the device.
| aci_gap_set_io_capability command | ||||||||
|---|---|---|---|---|---|---|---|---|
|
- aci_gap_set_security_requirements : Sets the security requirements for the device. Once the IO capability is defined, the aci_gap_set_security_requirements should be used to set all the security requirements the device needs.
| aci_gap_set_security_requirements command | ||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
All the security requirements parameters described above are defined in the Bluetooth LE application app_conf.h file:
/**
* Define IO capabilities
*/
#define CFG_IO_CAPABILITY GAP_IO_CAP_DISPLAY_ONLY
/**
* Define MITM modes
*/
#define CFG_MITM_PROTECTION GAP_MITM_PROTECTION_REQUIRED
/**
* Define Secure Connections Support
*/
#define CFG_SC_SUPPORT GAP_SC_OPTIONAL
/**
* Define Keypress Notification Support
*/
#define CFG_KEYPRESS_NOTIFICATION_SUPPORT GAP_KEYPRESS_NOT_SUPPORTED
The possible security requirements values are defined on the Middlewares\ST\STM32_BLE\stack\include\ble_const.h[OP1] as follows:
/**
* Define IO capabilities
*/
#define GAP_IO_CAP_DISPLAY_ONLY (0x00)
#define GAP_IO_CAP_DISPLAY_YES_NO (0x01)
#define GAP_IO_CAP_KEYBOARD_ONLY (0x02)
#define GAP_IO_CAP_NO_INPUT_NO_OUTPUT (0x03)
#define GAP_IO_CAP_KEYBOARD_DISPLAY (0x04)
/**
* Define MITM modes
*/
#define GAP_MITM_PROTECTION_NOT_REQUIRED (0x00)
#define GAP_MITM_PROTECTION_REQUIRED (0x01)
/**
* Define Secure Connections Support
*/
#define GAP_SC_NOT_SUPPORTED (0x00)
#define GAP_SC_OPTIONAL (0x01)
#define GAP_SC_MANDATORY (0x02)
/**
* Define Keypress Notification Support
*/
#define GAP_KEYPRESS_NOT_SUPPORTED (0x00)
#define GAP_KEYPRESS_SUPPORTED (0x01)
Once the security IO capability and security requirements are defined, an application can initiate a pairing procedure. The pairing procedure can be started by a GAP peripheral or central device using the aci_gap_set_security command. This command may send a security request to pair with the peer device. If already bonded, the command may only trigger the start of an encryption procedure on the link.
| aci_gap_set_security command | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
2.1.1. Pairing using the Passkey Entry method
This section describes an example of the main functions to be used in order to establish a pairing between two devices (authenticate the device, encrypt the link, and distribute the keys to be used on the next reconnections). To successfully pair with a device, IO capabilities must be correctly configured, depending on the IO capability available on the selected device.
The initialization commands are sent with the following parameters to perform LE legacy pairing with the Passkey Entry method.
The command aci_gap_set_io_capability (io_capability) is used on both devices in order to setup a Passkey Entry method to generate the keys:
/*Device_1: set IO_CAP_DISPLAY_ONLY */
tBleStatus ret;
ret = aci_gap_set_io_capability(IO_CAP_DISPLAY_ONLY);
if (ret != BLE_STATUS_SUCCESS)
PRINTF("Failure.\n");
/*Device_2: set IO_CAP_KEYBOARD_ONLY */
tBleStatus ret;
ret = aci_gap_set_io_capability(IO_CAP_KEYBOARD_ONLY);
if (ret != BLE_STATUS_SUCCESS)
PRINTF("Failure.\n");
Once the IO capability is defined, the aci_gap_set_security_requirements is used to set all the security requirements the device needs:
- MITM mode (authenticated link or not)
- OOB data present or not
- Enabling bonding or not
The following pseudocode example illustrates only the specific steps to be followed to set the authentication requirements for a device with: “MITM protection, no OOB data": this configuration is used to authenticate the link and to use the pairing process with Passkey Entry method.
NOTE: GAP_SC_NOT_SUPPORTED is used as the value for the SC_Support parameter (LE secure connections support), since this example targets a legacy pairing.
tBleStatus ret;
ret = aci_gap_set_security_requirements(CFG_BONDING_MODE, /* bonding mode is enabled */
GAP_MITM_PROTECTION_REQUIRED, /* MITM mode */
GAP_SC_NOT_SUPPORTED , /* SC pairing not supported */
GAP_KEYPRESS_NOT_SUPPORTED, /* keypress notification not supported */
7, /* min_encryption_key_size - CFG_ENCRYPTION_KEY_SIZE_MIN */
16, /* max_encryption_key_size - CFG_ENCRYPTION_KEY_SIZE_MAX */
GAP_PAIRING_RESP_NONE /* pairing response none - GAP_PAIRING_RESP_NONE */ );
if (ret != BLE_STATUS_SUCCESS)
PRINTF("Failure.\n");
Once the security IO capability and security requirements are defined, an application can initiate a pairing procedure by using aci_gap_set_security() on a GAP peripheral or central device:
tBleStatus ret;
ret = aci_gap_set_security(Connection_Handle, Security_Level, Force_Pairing);
if (ret != BLE_STATUS_SUCCESS)
PRINTF("Failure.\n");
Once the paring procedure is initiated by one of the two devices, Bluetooth® Low Energy stack event dispatcher raises the aci_gap_passkey_req_event (with related connection handle) on BLEEVT_App_Notification() to ask the user application to provide the password to be used to establish the encryption key. Bluetooth® Low Energy application has to provide the correct passkey by using the aci_gap_passkey_resp(conn_handle,passkey) API. When the aci_gap_passkey_req_event is raised on Device_1, it should set it through the aci_gap_passkey_resp() API, as follows:
void BLEEVT_App_Notification(const hci_pckt *hci_pckt)
{
....
case ACI_GAP_PASSKEY_REQ_VSEVT_CODE:
{
APP_DBG_MSG(">>== ACI_GAP_PASSKEY_REQ_VSEVT_CODE\n");
ret = aci_gap_passkey_resp(bleAppContext.BleApplicationContext_legacy.connectionHandle, CFG_FIXED_PIN);
if (ret != BLE_STATUS_SUCCESS)
{
APP_DBG_MSG("==>> aci_gap_passkey_resp : Fail, reason: 0x%02X\n", ret);
}
else
{
APP_DBG_MSG("==>> aci_gap_passkey_resp : Success\n");
}
}
break;
....
}
| Legacy pairing: Passkey Entry method |
|---|
 |
2.2. Secure connection use cases
For the Passkey Entry method, it is the same flow as for LE legacy pairing, the only thing to change is the value of the SC_Support parameter of the aci_gap_set_security_requirements() command to support secure connections:
#define GAP_SC_OPTIONAL (0x01) /* Supported but optional (i.e. a Legacy Pairing may be accepted) */
#define GAP_SC_MANDATORY (0x02) /* Supported but mandatory (i.e. do not accept Legacy Pairing but only Secure Connections v.4.2 Pairing) */
2.2.1. Pairing using Numeric Comparison
The initialization commands are sent with the following parameters to perform secure connections with the Numeric Comparison method:
aci_gap_set_io_capability(IO_CAP_KEYBOARD_DISPLAY)
aci_gap_set_authentication_req (1, /* bonding mode */
GAP_MITM_PROTECTION_REQUIRED, /* MITM 0x01*/
GAP_SC_MANDATORY, /*Secure Connections Pairing supported and mandatory */
GAP_KEYPRESS_NOT_SUPPORTED, /* keypress notification not supported */
CFG_ENCRYPTION_KEY_SIZE_MIN, /* min_encryption_key_size */
CFG_ENCRYPTION_KEY_SIZE_AXN, /* max_encryption_key_size */
GAP_PAIRING_RESP_NONE /* */)
Once the device is initialized, the advertising is started. Then, using ST BLE toolbox smartphone application, the connection is established, and a pairing request is sent with a numeric value to confirm. On the server side, the ACI_GAP_NUMERIC_COMPARISON_VALUE_VSEVT_CODE event is generated and the numeric value is printed. The application confirms the numeric value using the aci_gap_numeric_comparison_value_confirm_yesno command to establish pairing between the 2 devices:
| Secure Connection pairing |
|---|
3. How to decrypt the traffic using a sniffer
3.1. LE legacy pairing
When LE legacy pairing is used, a BLE sniffer is able to decrypt the traffic for each method:
- In the Just Works method, the TK is set to 0, so it is very easy for an attacker to brute force the STK and eavesdrop on the connection. The sniffer is able to do it.
- In the Passkey Entry method, the TK is a 6 digit number that is passed between the devices by the user through BLE. So, if an attacker is present during the pairing process and is able to sniff the values being exchanged, then it is fairly trivial to brute force the TK and use it to derive the STK and decrypt the connection. The sniffer is able to do it.
- In OOB method, the TK is exchanged using a different technology than BLE. If the OOB channel is protected from MITM attacks, then it can be assumed that the BLE connection is also protected from MITM attacks as well. Likewise, as long as the OOB channel is immune to eavesdropping during the pairing process, then the BLE connection also is immune from passive eavesdropping. In this case, since the TK is not exchanged over BLE, the sniffer is not able to decrypt the traffic without the TK. To decrypt the traffic, the TK needs to be entered into BLE sniffer software.
3.2. LE secure connections
When LE secure connections is used, the only way to decrypt the traffic is to use the debug key for secure connection. When the security manager is placed in a debug mode, the following Diffie-Hellman private / public key pairs are used:
- Private key: 3f49f6d4 a3c55f38 74c9b3e3 d2103f50 4aff607b eb40b799 5899b8a6 cd3c1abd
- Public key (X): 20b003d2 f297be2c 5e2c83a7 e9f9a5b9 eff49111 acf4fddb cc030148 0e359de6
- Public key (Y): dc809c49 652aeb6d 63329abf 5a52155c 766345c2 8fed3024 741c8ed0 1589d28b
Only one side (initiator or responder) needs to set secure connections debug mode in order for debug equipment to be able to determine the LTK and, therefore, be able to monitor the encrypted connection.
To enable this debug mode, add the following command before GAP/GATT initialization:
aci_hal_write_config_data(Offset = 0xD0, Length = 1, Value = 1)
4. Additional information - BLE characteristics and security permissions
4.1. BLE GATT characteristic security permissions
When a characteristic is created, the following security permissions could be given through the permissions field of ble_gatt_chr_def_t structure:
- 0x00: BLE_GATT_SRV_PERM_NONE (indicates no permissions are required to access the characteristic value)
- 0x01: BLE_GATT_SRV_PERM_AUTHEN_READ (indicates that the reading of the characteristic value requires an authenticated pairing (i.e. with MITM protection enabled))
- 0x04: BLE_GATT_SRV_PERM_ENCRY_READ (indicates that the reading of the characteristic value requires an encrypted link (The minimum encryption key size to access this characteristic value must be specified through the min_key_size field.))
- 0x08: BLE_GATT_SRV_PERM_AUTHEN_WRITE (indicates that the writing of the characteristic value requires an authenticated pairing (i.e. with MITM protection enabled))
- 0x20: BLE_GATT_SRV_PERM_ENCRY_WRITE (indicates that writing of the characteristic value requires an encrypted link (The minimum encryption key size to access this characteristic value must be specified through the min_key_size field.))
4.1.1. READ and WRITE properties
When a characteristic is created, the following properties could be set with properties bit field of ble_gatt_chr_def_t or ble_gatt_descr_def_t, indicating how the characteristic value and descriptor can be accessed:
/**
*@name GATT_SRV_CHAR_PROP
* @brief The following macro are used to define the characteristic properties as
* defined in BLUETOOTH CORE SPECIFICATION
*@{
*/
#define BLE_GATT_SRV_CHAR_PROP_NONE (0x00U)
/** If set, it permits broadcasts of the Characteristic Value using Server
* Characteristic Configuration Descriptor.
* If set, the Server Characteristic Configuration Descriptor shall exist. */
#define BLE_GATT_SRV_CHAR_PROP_BROADCAST (0x01U)
/** If set, it permits reads of the Characteristic Value. */
#define BLE_GATT_SRV_CHAR_PROP_READ (0x02U)
/** If set, it permit writes of the Characteristic Value without response. */
#define BLE_GATT_SRV_CHAR_PROP_WRITE_NO_RESP (0x04U)
/** If set, it permits writes of the Characteristic Value with response. */
#define BLE_GATT_SRV_CHAR_PROP_WRITE (0x08U)
/** If set, it permits notifications of a
* Characteristic Value without acknowledgment. If set, the Client
* Characteristic Configuration Descriptor shall exist. */
#define BLE_GATT_SRV_CHAR_PROP_NOTIFY (0x10U)
/** If set, it permits indications of a
* Characteristic Value with acknowledgment. If set, the Client Characteristic
* Configuration Descriptor shall exist. */
#define BLE_GATT_SRV_CHAR_PROP_INDICATE (0x20U)
/** If set, it permits signed writes to the
* Characteristic Value. */
#define BLE_GATT_SRV_CHAR_PROP_AUTH_SIGN_WRITE (0x40U)
/** If set, additional characteristic
* properties are defined in the Characteristic Extended Properties Descriptor.
* If set, the Characteristic Extended Properties Descriptor shall exist. */
#define BLE_GATT_SRV_CHAR_PROP_EXTENDED_PROP (0x80U)
4.2. AUTHEN_READ and AUTHEN_WRITE security permissions
After the discovery of services and characteristics, if the client tries to read or write a characteristic which requires authentication, an error is returned (ACI_GATT_ERROR_RESP_EVENT) with error_code = BLE_ATT_ERR_INSUFF_AUTHENTICATION (0x05, insufficient authentication).
In this case the client may increase the security level of the link to security mode 1 level 3 by sending aci_gap_set_security() command: a pairing starts if no bond was present. If level 3 is reached (authentication), the requirements for encryption are also satisfied.
4.3. ENCRY_READ and ENCRY_WRITE security permissions
After the discovery of the service and characteristic, if the client tries to read or write a characteristic which requires encryption, an error is returned (ACI_GATT_ERROR_RESP_EVENT) with error_code = BLE_ATT_ERR_INSUFF_ENCRYPT (0x0F, insufficient encryption).
In this case the client can increase the security level of the link to security mode 1 level 2 by sending the aci_gap_set_security() command: a pairing starts if no bond is present.
5. References