|
Coming soon |
1. STM32WB-WBA - Bluetooth® Low Energy security overview
1.1. Security features
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)
1.2. Pairing
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 are the IO capabilities, OOB authentication data availability, authentication requirements, key size. This exchange is done through the Pairing Request and Pairing Response packet and allow to determine the key generation method used in Phase 2.
Note: all data being exchanged during this phase is unencrypted.
1.2.2. Phase 2: Key Generation
The Key Generation phase is specific for each pairing methods. According to the capabilities exchange in phase 1, the key generation method is one of the following method:
- Just Works
- Passkey Entry
- Out of Band (OOB)
- Numeric Comparison: Only for LE Secure Connection
The key generation methods depend of IO capabilities values exchange in phase 1:
| Mapping of IO capabilities to key generation method |
|---|
1.2.2.1. LE Secure Connections
For LE Secure Connections, the 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.
1.2.2.2. LE Legacy Pairing
For LE Legacy Pairing, the phase 2 is called Short Term Key (STK) Generation. This methods uses and generates 2 keys:
1. Temporary Key (TK): a 128-bit temporary key used in the pairing process which is used to generate STK.
2. Short Term Key (STK): a 128-bit temporary key used to encrypt a connection following pairing.
Then, if bonding, LTK will be used for subsequent connections.
1.2.3. Phase 3: Transport Specific Key Distribution
Only LE Security Mode 1 is supported by STM32WB-WBA, this mode 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. LE Legacy Pairing
2.1. Use cases
2.2. How to decrypt the traffic
3. LE Secure Connection
Initialization (when no link is established)
Set the IO capability of the device with aci_gap_set_io_capability
| IO capability |
|---|
Set the authentication requirements for the device with aci_gap_set_authentication_req
| Set authentication requirement |
|---|
3.1. Legacy pairing and no fixed pin
- Initialization
aci_gap_set_io_capability(0x04 - IO_CAP_KEYBOARD_DISPLAY)
aci_gap_set_authentication_req (0, - no bonding mode
1, - mitm_mode
0, - SC pairing not supported
0, - keypress notification not supported
7, - min_encryption_key_size
16, - max_encryption_key_size
1, - do not use a fixed pin
111111, - fixed pin
0 - identity address type)
| Legacy pairing and no fixed pin |
|---|
3.2. Legacy pairing and fixed pin initiated by the peripheral
- Initialization
aci_gap_set_io_capability(0x00 - IO_CAP_DISPLAY_ONLY)
aci_gap_set_authentication_req (0, - no bonding mode
0, - no mitm
0, - SC pairing not supported
0, - keypress notification not supported
7, - min_encryption_key_size
16, - max_encryption_key_size
0, - use a fixed pin
111111, - fixed pin (used)
0 - identity address type)
| Legacy pairing and fixed pin |
|---|
3.3. Pairing Secure connection
- Initialization
aci_gap_set_io_capability(0x04 - IO_CAP_KEYBOARD_DISPLAY)
aci_gap_set_authentication_req (0, - no bonding mode
1, - mitm mode
1, - SC pairing supported but optional
0, - keypress notification not supported
7, - min_encryption_key_size
16, - max_encryption_key_size
1, - do not use a fixed pin
111111, - fixed pin (not used)
0 - identity address type)
| Secure Connection pairing |
|---|
4. Additional information - BLE characteristics and security permissions
4.1. STM32WB - BLE GATT characteristic
When a characteristic is created (aci_gatt_add_char), 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 services and characteristics, 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 need of 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 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 of starting 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 server side which sends aci_gap_authorization_resp(conn_handle, authorize) then the client can read/write the characteristic.