STM32WB-WBA Bluetooth^® LE Security

This message will disappear after all relevant tasks have been resolved.

Semantic MediaWiki

There are 1 incomplete or pending task to finish installation of Semantic MediaWiki. An administrator or user with sufficient rights can complete it. This should be done before adding new data to avoid inconsistencies.

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 STM32WB and STM32WBA, 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.

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 upgrade 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 (LE legacy pairing): Short Term Key (STK) Generation
Phase 2 (LE Secure Connections): Long Term Key (LTK) Generation
Phase 3: Transport Specific Key Distribution

Pairing flowchart

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 is the IO capabilities, OOB authentication data availability, authentication requirements, and key size. This exchange is performed 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

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:

Just Works
Passkey Entry
Out of Band (OOB): Dedicated wiki page on this topic
Numeric Comparison: Only for LE Secure Connections

The key generation methods depend on IO capabilities value exchange in phase 1:

Mapping of IO capabilities to key generation method

In the table above, authenticated means MITM protection required and unauthenticated means MITM protection is not required.

1.2.2.1 LE Legacy Pairing - Phase 2: 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 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 - Phase 2: Long Term Key (LTK) Generation

For LE Secure Connections, phase 2 is called Long Term Key (LTK) Generation. This method uses and generates 1 key:

1. 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 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

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 a device you think you are communicating with really is that device and not some other, imposter device. Sometimes, you want to take the idea further and verify that the person using the device you are communicating with is who they say they are.

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’s 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.

STM32WB-WBA supports the LE Security Mode 1 which has the following security levels:

1. No security (No authentication and no encryption)
2. Unauthenticated pairing with encryption (no MITM protection)
3. Authenticated pairing with encryption (MITM protection)
4. Authenticated LE Secure Connections pairing with encryption using a 128-bit strength encryption key

2 How to setup the pairing with STM32WB or STM32WBA application

2.1 Parameters and commands overview

Two commands are used during the initialization of the device (e.g when the device is not in connected state):

aci_gap_set_io_capability : Sets the IO capabilities of the device

aci_gap_set_io_capability command

aci_gap_set_authentication_requirement : Sets the authentication requirements for the device

aci_gap_set_authentication_requirement command

All the parameters described above are defined in the app_conf.h file:

/**
 * Define BD_ADDR type: define proper address. Can only be GAP_PUBLIC_ADDR (0x00) or GAP_STATIC_RANDOM_ADDR (0x01)
 */
#define CFG_IDENTITY_ADDRESS              GAP_PUBLIC_ADDR
**
 * Define IO Authentication
 */
#define CFG_BONDING_MODE                 (1)
#define CFG_FIXED_PIN                    (111111)
#define CFG_USED_FIXED_PIN               (0)
#define CFG_ENCRYPTION_KEY_SIZE_MAX      (16)
#define CFG_ENCRYPTION_KEY_SIZE_MIN      (8)

/**
 * Define IO capabilities
 */
#define CFG_IO_CAPABILITY_DISPLAY_ONLY        (0x00)
#define CFG_IO_CAPABILITY_DISPLAY_YES_NO      (0x01)
#define CFG_IO_CAPABILITY_KEYBOARD_ONLY       (0x02)
#define CFG_IO_CAPABILITY_NO_INPUT_NO_OUTPUT  (0x03)
#define CFG_IO_CAPABILITY_KEYBOARD_DISPLAY    (0x04)

#define CFG_IO_CAPABILITY                     CFG_IO_CAPABILITY_DISPLAY_YES_NO

/**
 * Define MITM modes
 */
#define CFG_MITM_PROTECTION_NOT_REQUIRED      (0x00)
#define CFG_MITM_PROTECTION_REQUIRED          (0x01)

#define CFG_MITM_PROTECTION                   CFG_MITM_PROTECTION_REQUIRED

/**
 * Define Secure Connections Support
 */
#define CFG_SECURE_NOT_SUPPORTED              (0x00)
#define CFG_SECURE_OPTIONAL                   (0x01)
#define CFG_SECURE_MANDATORY                  (0x02)

#define CFG_SC_SUPPORT                        CFG_SECURE_OPTIONAL

/**
 * Define Keypress Notification Support
 */
#define CFG_KEYPRESS_NOT_SUPPORTED            (0x00)
#define CFG_KEYPRESS_SUPPORTED                (0x01)

#define CFG_KEYPRESS_NOTIFICATION_SUPPORT     CFG_KEYPRESS_NOT_SUPPORTED

Once Bluetooth® LE link is established, the pairing procedure can be started by:

the central using aci_gap_send_pairing_req command

aci_gap_send_pairing_req command

the peripheral using aci_gap_peripheral_security_req command

aci_gap_peripheral_security_req command

2.2 Legacy pairing use cases

2.2.1 Passkey Entry using a fixed pin

The initialization commands are sent with the following parameters to perform LE Legacy Pairing with Passkey Entry method using a fixed pin:

aci_gap_set_io_capability(0x00 - IO_CAP_DISPLAY_ONLY) 
aci_gap_set_authentication_req (1, - bonding mode
                             1, - MITM
                             0, - SC pairing not supported
                             0, - keypress notification not supported
                             8, - min_encryption_key_size
                             16, - max_encryption_key_size
                             0, - use a fixed pin
                             111111, - fixed pin (used)
                             0 - identity address type)

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 the pin code defined in the application (here 111111) to establish pairing between the 2 devices:

Legacy pairing: Passkey Entry using a fixed pin

2.2.2 Passkey Entry without using a fixed pin

The initialization commands are sent with the following parameters to perform LE Legacy Pairing with Passkey Entry method without using a fixed pin:

aci_gap_set_io_capability(0x00 - IO_CAP_DISPLAY_ONLY) 
aci_gap_set_authentication_req (1, - bonding mode
                             1, - MITM
                             0, - SC pairing not supported
                             0, - keypress notification not supported
                             8, - min_encryption_key_size
                             16, - max_encryption_key_size
                             1, - do not use a fixed pin
                             111111, - fixed pin (unused)
                             0 - identity address type)

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 pin code (here 123456). On the server side, the ACI_GAP_PASS_KEY_REQ_EVENT event is generated and the application responds using aci_gap_pass_key_resp command with the same pin in the parameter to establish pairing between the 2 devices:

Legacy pairing: Passkey Entry without using a fixed pin

2.3 Secure Connections use cases

For Passkey Entry method, it's the same flow than for LE Legacy Pairing, the only thing to change is the value of SC_Support parameter of aci_gap_set_authentication_requirement command to support secure connections (e.g 0x01: Secure Connections Pairing supported but optional 0x02: Secure Connections Pairing supported and mandatory (SC Only Mode)).

2.3.1 Numeric Comparison

The initialization commands are sent with the following parameters to perform Secure Connections with numeric comparison method:

aci_gap_set_io_capability(0x04 - IO_CAP_KEYBOARD_DISPLAY) 
aci_gap_set_authentication_req (1, - bonding mode
                             1, - MITM
                             2, - Secure Connections Pairing supported and mandatory
                             0, - keypress notification not supported
                             8, - min_encryption_key_size
                             16, - max_encryption_key_size
                             0, -  Use a fixed pin
                             111111, - fixed pin (not used)
                             0 - identity address type)

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_EVENT event is generated and the numeric value is printed. The application confirms the numeric value using 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, BLE sniffer is able to decrypt the traffic for each method:

In 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 passkey 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 isn't exchanged over BLE, the sniffer isn't 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 Mode. When the Security Manager is placed in a Debug mode, the following Diffie-Hellman private / public key pairs are not 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 at GAP/GATT initialization, see Ble_Hci_Gap_Gatt_Init_1 user section in Ble_Hci_Gap_Gatt_Init function:

aci_hal_write_config_data(Offset = 0x35 - CONFIG_DATA_SC_KEY_TYPE_OFFSET, Length = 1, Value = 1 - debug)

4 Additional information - BLE characteristics and security permissions

4.1 BLE GATT characteristic security permissions

When a characteristic is created (aci_gatt_add_char), the following security permissions could be given:

0x00: none
0x01: AUTHEN_READ (need authentication to read)
0x02: AUTHOR_READ (need authorization to read)
0x04: ENCRY_READ (need encryption to read)
0x08: AUTHEN_WRITE (need authentication to write)
0x10: AUTHOR_WRITE (need authorization to write)
0x20: ENCRY_WRITE (need encryption to write)

4.1.1 READ and WRITE properties

A characteristic is created with properties READ and WRITE.

4.2 AUTHEN_READ and AUTHEN_WRITE security permissions

After the discovery of the service and characteristic, if the client tries to read or write this characteristic, an error is returned (ACI_GATT_ERROR_RESP_EVENT) with error_code=0x05 (insufficient authentication).

Set MITM (in aci_gap_set_authentication_requirement) is necessary and needs to start pairing to be able to read/write the characteristic with 'need authentication' permissions.

Security permission 'need authentication' is more restrictive than 'need encryption'.

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 this characteristic, an error is returned (ACI_GATT_ERROR_RESP_EVENT) with error_code=0x0F (insufficient encryption).

If the devices are paired and encryption is started, read and write operations can be done. No need to set MITM and need to start pairing to be able to read/write the characteristic with 'need encryption' permissions.

4.4 AUTHOR_READ and AUTHOR_WRITE security permissions

The way to use characteristic with 'need authorization' permissions: after the connection_complete_event, the server sends the command aci_gap_set_authorization_requirement (for current connection handle) the master initiates pairing. When the pairing is complete, ACI_GAP_AUTHORIZATION_REQ_EVENT is generated on the server side which sends aci_gap_authorization_resp(conn_handle, authorize). Then the client can read/write the characteristic.

5 References

↑ Bluetooth^®LE Security Study Guide

[1] Bluetooth^®LE Security Study Guide

[1]

STM32WB-WBA Bluetooth® LE Security

1 Bluetooth® Low Energy security overview