Note: This KBA has been deprecated. Please refer to the following KBA: Using Bluetooth security features in Silicon Labs Bluetooth SDK

Introduction

This article demonstrates Bluetooth Smart 4.2 security features used in Simplicity Studio Bluetooth Smart SDK v2.0.0 for Blue Gecko products. The attached example is the health thermometer sample application extended with MITM and BLE 4.2 secure connections.

The BLE SDK v2.0.0 supports BLE Secure Connections according to Bluetooth specification 4.2. Including ECDH key exchange and numeric comparison with MITM. The attached example is demonstrating these features.

The BLE SDK v2.0.0 drops the plugin system, so the code examples are much simpler. However you cannot set security features on Application Builders UI as in the older BLE SDK versions. In the new SDK you have to configure every settings via API calls.

Setting up the security

To set up the security features you need to do the following steps:

1. Setting up attribute permissions in GATT
2. Enable bonding
3. Set up security manager
4. Increase security level
5. Handle security manager stack events

1. Setting up attribute permissions in GATT

In this example we don’t modify the GATT to be compatible with the Health Thermometer Service define by Bluetooth SIG.

But in general if you want that the read only allowed through an encrypted connection set the authenticated_read property to true in the gatt_db.bgroj file.

For example:

<characteristic uuid="7baaa53f-1569-4d3d-b59b-0af58da719d4" id="my_secret">

  <!-- my sensitive data -->

  <properties read="true" authenticated_read="true"/>

  <value type="hex" length="20" />

 </characteristic>

2. Enable bonding

To enable secure connection, first we need to allow bonding. The bonding process stores the keys which are used during secure communication.

We call the gecko_cmd_sm_set_bondable_mode(1) API function after the boot in the gecko_evt_system_boot_id event.

        case gecko_evt_system_boot_id:

          printf("Boot\r\n");

          /* delete all bondings to force the pairing process */

          gecko_cmd_sm_delete_bondings();

          printf("All bonding deleted\r\n");

          gecko_cmd_sm_configure(0x0F, sm_io_capability_displayyesno); /* Numeric comparison */

          /* enable bondable to accommodate certain mobile OS */

          gecko_cmd_sm_set_bondable_mode(1);

          /* Set advertising parameters. 100ms advertisement interval. All channels used.

           * The first two parameters are minimum and maximum advertising interval, both in

           * units of (milliseconds * 1.6). The third parameter '7' sets advertising on all channels. */

          gecko_cmd_le_gap_set_adv_parameters(160,160,7);

          /* Start general advertising and enable connections. */

          gecko_cmd_le_gap_set_mode(le_gap_general_discoverable, le_gap_undirected_connectable);

          break;

3. Set up security manager

We have to use the gecko_cmd_sm_configure(flags, io_capabilities) API to set up security configuration.

The capabilities parameter tells what kind of user input and output methods are available on our device. The different io capabilities leads to different pairing methods.

In the example we call the gecko_cmd_sm_configure(0x0F, sm_io_capability_keyboarddisplay) in the gecko_evt_system_boot_id event, to force the BLE 4.2 secure connection and numeric comparison MITM protection method.

4. Increase the security level

In the connection opened event handler we have to increase call the gecko_cmd_sm_increase_security API function. This will trigger the pairing process.

        case gecko_evt_le_connection_opened_id:

          printf("Connected\r\n");

          /* Store the connection ID */

          activeConnectionId = evt->data.evt_le_connection_opened.connection;

          /* The HTM service typically indicates and indications cannot be given an encrypted property so

           * force encryption immediately after connecting */

          gecko_cmd_sm_increase_security(activeConnectionId);

          break;

Please note that the recommended way of starting the bonding process isn’t to use increase security, but to initiate the process (automatically) when a authenticated/encrypted GATT characteristic is read/written. In this example did not set up the up attribute permissions so we force pairing/bonding manually.

5a. Handle the gecko_evt_sm_passkey_display_id event

The gecko_evt_sm_passkey_display_id event indicates a request to display the passkey to the user. In the example it prints the passkey to the console.

        case gecko_evt_sm_passkey_display_id:

          printf("Passkey display\r\n");

          printf("Enter this passkey on the tablet:\r\n%d\r\n",

                          evt->data.evt_sm_passkey_display.passkey);

          break;

5b. Handle the gecko_evt_sm_passkey_request_id event

The gecko_evt_sm_passkey_request_id event indicates a request for the user to enter the passkey displayed on the remote device. In the example we initiate the passkey reading from the console with setting read_pk to true.

        case gecko_evt_sm_passkey_request_id:

          printf("Passkey request\r\n");

          printf("Enter the passkey you see on the tablet\r\n");

          read_pk = true;

          break;

The actual passkey reading implemented in the passkey_read function. When the reading done the function calls the sm_enter_passkey API command to push the received passkey to the stack.

If the passkey was valid and the bonding completed the stack raise a gecko_msg_sm_bonded_evt_t. If the passkey was invalid or the bonding failed because of any other reason the stack will raise a gecko_evt_sm_bonding_failed_id event.

5c. Handle gecko_evt_sm_confirm_passkey_id event

This event indicates a request to display the passkey to the user then asks to confirm the displayed passkey. The example prints the pin to the console then ask for confirmation on the console with setting the read_y_n flag to true.

case gecko_evt_sm_confirm_passkey_id:    

  printf("Confirm passkey\r\n");

          printf("Are you see the same passkey on the tablet: %d (y/n)?\r\n",

evt->data.evt_sm_confirm_passkey.passkey);

          read_y_n = true;

          break;

The confirmation reading implemented in the yes_no_read function. The gecko_cmd_sm_passkey_confirm called to accept or reject the displayed passkey depending on the users answer.

Test the MITM protection

1. Open a terminal and connect to the J-Link CDC UART Port with 115200 kbps, 8N1, no flow-control. After the Blue Gecko booted up you should see the following:

2. Open the Bluegecko App on your tablet/phone. Tap on the health thermometer. Then click on the other tab. Then tap on Thermometer Example device.

3. You will be prompted to pairing, the default method is the numeric comparison method. Press ‘y’ on the terminal and press Pair on the tablet/Phone.

Please note that on some older Android or IOS version you may get pairing error.

This is because we are forcing the BLE 4.2 security connections when calling the

gecko_cmd_sm_configure(0x0F, sm_io_capability_displayyesno) API function after boot.

Feel free experiment with different settings. This will lead to different pairing methods.

Once the pairing completed you will see the temperature updating.

4. Once you have paired your device and you want to pair it again, you have to clear the bonding from the phone/tablet. On the Blue Gecko all bonding deleted after boot to force the pairing and bonding process. In a "real" application you should not do this.