STM32WB-WBA BLE security - Out Of Band pairing

Coming soon

1. Bluetooth^® Low Energy Security - Out Of Band Pairing method

This article is dedicated to Out Of Band (OOB) pairing, for global information regarding BLE security features, refer to BLE security wiki page.

In this page, an overview of the specific key generation method:

• Out of Band (OOB)

The Out of Band (OOB) mechanism is used to both discover the devices as well as to exchange or transfer cryptographic numbers used in the pairing process. It needs to be effective from a security point of view and should be resistant to Man In The Middle (MITM) attacks.

For LE Secure Connection Pairing, if Out Of Band pairing method is used, the public keys, nonce and confirmation values are all exchanged via a different technology than Bluetooth^® Low Energy such as NFC or UART.

For LE Legacy Pairing, if Out Of Band pairing method is used, the TK is exchanged using a different wireless technology such as NFC or UART. The main advantage to this method is that a very large TK can be used, up to 128 bits.

OOB via NFC example

Two commands are specific to OOB method , to get and set the OOB data:

• ACI_GAP_SET_OOB_DATA which allow to generate OOB data or to set OOB data from peer device received via OOB communication. To generate the OOB data, all the parameters need to be set to zero
  

ACI_GAP_SET_OOB_DATA command - Input parameters

ACI_GAP_SET_OOB_DATA command - Output parameters

• ACI_GAP_GET_OOB_DATA which allow to get the (i.e. to extract from the Stack) the OOB data generated by the Stack itself.
  

ACI_GAP_GET_OOB_DATA command - Input parameters

ACI_GAP_GET_OOB_DATA command - Output parameters

During the phase 1 of pairing procedure, e.g Pairing Feature Exchange, the devices exchange their capabilities using pairing request/response. The frame of these messages contain one field of 1 byte named "OOB Data Flag" which indicate if OOB Authentication data are present or not.
For the definition of “OOB Data Flag”, refer to the table below:

OOB Data Flag Description

2. OOB in LE Secure Connection Pairing

In LE Secure Connections pairing, if one or both devices have out of band authentication data, then the Authentication Requirements Flags (MITM) shall be ignored when selecting the pairing method and the Out of Band pairing method shall be used. Otherwise, the IO capabilities of the device shall be used to determine the pairing method, refer to pairing phase 2 : Key generation.

Rules for using Out-of-Band and MITM flags for LE Secure Connections pairing
File:Connectivity: SC rules oob flag and mitm.png

In the following description, it is considered the case where a smartphone connects a STM32WB-WBA and STM32WB-WBA provides OOB data and send it through NFC.

2.1. Commands sequence for pairing initialization, public key generation, generation and recovery of OOB data on WB-WBA

See below, the commands sequence for pairing initialization, public key generation, generation and recovery of OOB data on WB-WBA:

/* Initialize IO capability */
aci_gap_set_io_capability(0x00-display only);

/* Initialize authentication */
aci_gap_set_authentication_requirement(0x01 - bonding, 0x00 - no MITM, 0x02 - SC Support, 0x00 - keypress not supported, 0x08 -  encryption key size min, 0x10 - encryption key size max, 0x00 - fixed pin, 0x00000000 - fixed pin value, 0x00 - public address);

/* Sequence to force the regeneration of the EDCH_public key on OOB source device */
uint8_t ALL_EVENTS[8]={0xDF,0x18,0x03,0x00,0x00,0x00,0x00,0x00};
hci_le_set_event_mask(ALL_EVENTS);

/* generation of a new P-256 public key */
Hci_le_read_local_p256_public_key();

/* Reception of META EVENT */
HCI_LE_READ_LOCAL_P256_PUBLIC_KEY_COMPLETE_EVENT

/* OOB data generation */
aci_gap_set_oob_data(0x00 - device type, 0x00 - address type, 0x00 - address, 0x00 - oob data type, 0x00 - oob data len, 0x00 - oob data);

/* OOB data recovery */
aci_gap_get_oob_data(0x01-random, address type, address, oob data len, oob data);
aci_gap_get_oob_data(0x02-confirm, address type, address, oob data len, oob data);

Each part of the previous sequence is detailed in the following section.

2.2. Pairing initialization commands on peripheral side

Pre-requisite before pairing request: initialization of pairing conditions with 2 commands:

/* Set the IO capability of the device */ 
aci_gap_set_io_capability(0x00-display only);
/* Set the authentication requirements for the device */ 
aci_gap_set_authentication_requirement(0x01 - bonding, 0x00 - no MITM, 0x02 - SC Support, 0x00 - keypress not supported, 0x08 -  encryption key size min, 0x10 - encryption key size max, 0x00 - fixed pin, 0x00000000 - fixed pin value, 0x00 - public address);

2.3. Public Key generation

The peripheral is the device where the OOB data will be extracted. The central is the device where OOB data will be set.

Following sequence is done before the connection:

On peripheral side:
Sequence to force the regeneration of the EDCH_public key on source device
First action: set LE Event Mask to require which LE events are generated by the HCI for the host.

hci_le_set_event_mask command is used to control which LE events are generated by the HCI for the Host.
Default value of this event mask is 0x000000000003185F. Refer to hci_le_set_event_mask command description.
To receive LE Read Local P-256 Public Key Complete Event, bitmask 0x80 is needed.
The new mask value is 0x00000000000318DF.

uint8_t ALL_EVENTS[8]={0xDF,0x18,0x03,0x00,0x00,0x00,0x00,0x00};
hci_le_set_event_mask(ALL_EVENTS);

Second action: generation of a new P-256 public key (first action necessary to receive the event)

Hci_le_read_local_p256_public_key();

HCI_LE_META_EVENT event received :

HCI_LE_READ_LOCAL_P256_PUBLIC_KEY_COMPLETE_EVENT

contains Local_P256_Public_Key field.

2.4. OOB data generation

Command used to generate OOB data on device data source:

aci_gap_set_oob_data(0x00 - device type, 0x00 - address type, 0x00 - address, 0x00 - oob data type, 0x00 - oob data len, 0x00 - oob data);

Previous command is sent with all data equal to zero.

2.5. OOB data recovery

For SC secure pairing:
Two commands used to recover the generated OOB data on device data source
First command:

aci_gap_get_oob_data(oob_data_type=0x01-random);

HCI_COMMAND_COMPLETE_EVENT event received, contains following fields:
address_type
address
OOB_data_type 0x01 (Random SC)
OOB_data_length
OOB_data : RANDOM_DATA – local pairing data intended to the remote device to be sent via NFC

Second command:

aci_gap_get_oob_data(oob_data_type=0x02-confirm);

HCI_COMMAND_COMPLETE_EVENT event received, contains following fields:
address_type
address
OOB_data_type 0x02 (Confirm SC)
OOB_data_length
OOB_data : CONFIRM_DATA – local pairing data intended to the remote device to be sent via NFC

RANDOM_DATA and CONFIRM_DATA generated by the BLE stack are written to ST25 (NFC shield).

2.6. OOB data written into NFC shield

Below a code example of OOB data written into NFC shield:

Ndef_Bluetooth_OOB_t NdefBle = { 


                                    .LeOptionalMask = (NDEF_BLUETOOTH_OPTION(BLUETOOTH_EIR_LE_SECURE_CONNECTIONS_CONFIRMATION_VALUE) |
                                                       NDEF_BLUETOOTH_OPTION(BLUETOOTH_EIR_LE_SECURE_CONNECTIONS_RANDOM_VALUE)),

                                    .LocalName = "ST25OOB",
                                    .OptionalMask = NDEF_BLUETOOTH_OPTION(BLUETOOTH_EIR_COMPLETE_LOCAL_NAME),

                                    .Type = NDEF_BLUETOOTH_BLE,
                                    .Role = NDEF_BLE_ROLE_PERIPH_ONLY,
                                    .DeviceAddressType = NDEF_BLE_PUBLIC_ADDRESS_TYPE

                                  };


  for(int i = 5; i >= 0; i --)
    NdefBle.DeviceAddress[i] = bd_addr[5-i];

   status = aci_gap_get_oob_data(1, &at,add,&len, rand);
   status = aci_gap_get_oob_data(2, &at,add,&len, hash);

  for(int i = 5; i >= 0; i --)
    NdefBle.DeviceAddress[i] = add[5-i];
  for(int i = 15; i >= 0; i --)
  {
    NdefBle.SimplePairingRandomizer[i] = rand[15-i];
    NdefBle.SimplePairingHash[i] = hash[15-i];
  }
   NfcTag_SelectProtocol(NFCTAG_TYPE5);

   NFC04A1_NFCTAG_Init(0);
   NDEF_ClearNDEF();
   NDEF_AppendBluetoothOOB(&NdefBle, NULL);

2.7. Transfer of OOB data through NFC

• RANDOM_DATA = rb
  
• CONFIRM_DATA = Cb
  

Random data and Confirm Data transferred through NFC
File:phoneNFC.png

2.8. Sequence diagram of OOB data transfer in LE Secure Connection - central generates OOB data

OOB pairing sequence

3. OOB in LE Legacy Pairing

In LE legacy pairing, if both devices have Out of Band authentication data, then the Authentication Requirements Flags shall be ignored when selecting the pairing method and the Out of Band pairing method shall be used. Otherwise, the IO capabilities of the device shall be used to determine the pairing method, refer to pairing phase 2 : Key generation.

Rules for using Out-of-Band and MITM flags for LE legacy pairing
File:Connectivity: LE Legacy Pairing oob flag mitm.png

In the following description, it is considered the case where two WBs are connected and exchange OOB data via UART.
Both devices MUST set their OOB data flag if they want to use OOB for pairing.
In case of LE Legacy Pairing, only one device generates the TK, the both are using the same TK.

3.1. Commands sequence for pairing initialization, generation and recovery of OOB data on WB/WBA

Sequence to be done in Ble_Hci_Gap_Gatt_Init function (in app_ble.c)

/* Initialize IO capability */
aci_gap_set_io_capability(0x00-display only)

/* Initialize authentication */
aci_gap_set_authentication_requirement(0x01- bonding, 0x00-no MITM, SC_Support=0x01, 0x00-fixed pin, 0x00000000-fixed pin value)

/* OOB data generation */
Aci_gap_set_oob_data(device_type=0x00, Address_type=0x00, address=0x00, oob_data_type=0, oob_data_len=0, oob_data=0)

/* OOB data recovery */
Aci_gap_get_oob_data(oob_data_type=0x00-TK)

3.2. Pairing initialization commands on peripheral side

Pre-requisite before pairing request: initialization of pairing conditions with 2 commands:

aci_gap_set_io_capability(0x00-display only)
aci_gap_set_authentication_requirement(0x01- bonding, 0x00-no MITM, SC_Support=0x00, 0x00-fixed pin, 0x00000000-fixed pin value)

3.3. OOB data generation

Command used to generate OOB data on device data source:

Aci_gap_set_oob_data(device_type=0x00, Address_type=0x00, address=0x00, oob_data_type=0, oob_data_len=0, oob_data=0)

Previous command is sent with all data equal to zero.

3.4. OOB data recovery

For LE Legacy pairing:
To recover the generated OOB data on device data source:

Aci_gap_get_oob_data(oob_data_type=0x00-TK)

HCI_COMMAND_COMPLETE_EVENT event received, contains following fields:
address_type
address
OOB_data_type 0x00 (TK)
OOB_data_length
OOB_data : TK

3.5. Example of OOB data transfer in Legacy Pairing - central generates OOB data

OOB pairing sequence

4. ST example : Out Of Band pairing

4.1. STM32WB55 + X-NUCLEO-NFC04A1 and Android smartphone

The ST25DV-I2C secure connection out-of-band pairing demonstration runs on the STM32WB55 board plus a X-NUCLEO-NFC04A1 shield, featuring a ST25DV-I2C tag connected to an STM32WB55 device through the I2C bus. A user manual is also available describing the demonstration and a video presents the demonstration.

4.2. LE Secure connection OOB pairing using UART between two STM32WB55

This example based on P2P Client and P2P Server application demonstrates the exchange of OOB data between two STM32WB55 using UART and demonstrates how to manage LE secure connection OOB pairing. Examples available under STM32 Hotspot GitHub: Client application and Server application .

4.3. LE Legacy OOB pairing using UART between two STM32WB55

This example based on P2P Client and P2P Server application demonstrates the exchange of OOB data between two STM32WB55 using UART and demonstrates how to manage LE Legacy OOB pairing. Examples available under STM32 Hotspot GitHub: Client application and Server application .