Using Bluetooth Security Features in Silicon Labs Bluetooth SDK

Introduction

This document introduces the Bluetooth security features and terms, then summarizes the practical usage of GATT permissions and pairing processes using the Silicon Labs Bluetooth SDK.

Bluetooth Security Basics

The most common threats in wireless communications are:

Bluetooth defines 5 distinct security features against these threats:

These features are implemented in different layers of the Bluetooth stack.

Pairing

Bluetooth uses Secure Simple Pairing (SSP) pairing model. The actual pairing process depends on the device I/O capabilities and the security requirements defined by the application.

More details can be found in Pairing Processes post.

Bonding

Authentication

A characteristic may be allowed to be read by any device, but only written by an authenticated device. Similarly, if a characteristic can be written, it does not mean the characteristic can also be read. Each individual characteristic could have different security properties.

Encryption

Notice: No encryption of broadcast data

Attribute Permissions

Security Levels

Security level is a property of a connection. Using different security features can lead to different security levels per connection. The different levels summarized below.

Security LevelDescription
Level 1No security
Level 2Unauthenticated pairing with encryption (paired with just work method)
Level 3Authenticated pairing with encryption (paired with legacy pairing)
Level 4Authenticated Secure Connections pairing with encryption using a 128-bit strength encryption key (Paired with LE secure pairing which is Bluetooth 4.2 feature)

Privacy

Public address is fixed and unique to a device Random address can change over time and hides the public address from unwanted devices Bonded devices can resolve the public address.

Bluetooth 4.2 Security Features

Using Security Features in Silicon Labs Bluetooth SDK

To use the security features you need to do the following steps:

  1. Set up attribute permissions in GATT.

  2. Set up security manager.

  3. Set up bonding (enabled/disable/delete).

  4. Increase security level (optional).

  5. Handle security manager stack events by the application.

Set up Attribute Permissions in GATT

The characteristics access and security properties are defined in the gatt.xml file by the XML attribute properties and its parameters, which must be used inside the characteristic XML attribute tags. Alternatively, Visual GATT Editor can be also used for defining the GATT elements and their permissions. The table below describes the parameters that can be used for defining attribute permissions.

attribute propertyDescription
readCharacteristic can be read by a remote device
writeCharacteristic can be written by a remote device
bonded_readReading the characteristic value requires an encrypted link. Devices must also be bonded at least with Just Works pairing
bonded_writeWriting the characteristic value requires an encrypted link. Devices must also be bonded at least with Just Works pairing
authenticated_readReading the characteristic value requires an authentication. To read the characteristic with this property the remote device has to be bonded using MITM protection and the connection must be also encrypted
authenticated_writeWriting the characteristic value requires an authentication. To write the characteristic with this property the remote device has to be bonded using MITM protection and the connection must be also encrypted
encrypted_readReading the characteristic value requires an encrypted link. iOS 9.1 and newer devices must also be bonded
encrypted_writeWriting the characteristic value requires an encrypted link. iOS 9.1 and newer devices must also be bonded

GATT Examples

The following are examples for setting up attribute permissions for a characteristic.

Example 1 — No restrictions

In this case, properties ensure that reading and writing the characteristic is without any restriction. It does not require authentication or encrypted link. Any GATT client can read or write it.

Example 2 — Encrypted write

Now let's set up the characteristic differently.

Example 3 — Authenticated write

Now let's modify the characteristic properties again.

In this case, reading the reading the characteristic is without any restriction. However, writing requires authentication, which means the remote device must be bonded with man in the middle (MITM) protection enabled. As a result, the characteristic cannot be accessed in case of just works pairing used. Writing this characteristic in the first time will trigger the pairing process.

Setting up the Security Manager

The application uses the gecko_cmd_sm_configure(flags, io_capabilities) API to set up the security configuration. The io_capabilities and flags parameters affect the security level which the devices will use and lead to different pairing mechanisms.

The io_capabilities parameter informs the stack about the possible user input and output method that is available on the device. See the available options here below:

ValueEnumerationDescription
0sm_io_capability_displayonlyDisplay Only
1sm_io_capability_displayyesnoDisplay with Yes/No-buttons
2sm_io_capability_keyboardonlyKeyboard Only
3sm_io_capability_noinputnooutputNo Input and No Output
4sm_io_capability_keyboarddisplayDisplay with Keyboard

The flags parameter controls different application specific security requirements. This parameter gives flexibility to the application to decide how strictly to use or not use at all the Bluetooth security features. The table below shows the different options:

BitmaskDescription
bit 00: Allow bonding without MITM protection
1: Bonding requires MITM protection
bit 10: Allow encryption without bonding
1: Encryption requires bonding. Note that this setting will also enable bonding.
bit 20: Allow bonding with legacy pairing
1: Secure connections only
bit 30: Bonding request does not need to be confirmed
1: Bonding requests need to be confirmed. Received bonding requests are notified with sm_confirm_bonding events.
bit 40: Allow all connections
1: Allow connections only from bonded devices
bit 5 to 7Reserved

If the flags parameter is 0 and no application specific requirement set, the pairing method depends only on the I/O capabilities of the initiator and the responder device (shown as I and R on the table below).

Responder/Initiator I/O capabilitiesDisplay OnlyDisplayYesNoKeyboardOnlyNoInputNoOutputKeyboardDisplay
Display onlyJust WorksJust WorksPasskey Entry(R displays,I inputs)Just WorksPasskey Entry (R displays,I inputs)
DisplayYesNoJust WorksNumeric ComparisonPasskey Entry (R displays, I inputs)Just WorksNumeric Comparison
KeyboardOnlyPasskey Entry (I displays, R inputs)Passkey Entry (I displays, R inputs)Passkey Entry (R and I inputs)Just WorksPasskey Entry(I displays, R inputs)
NoInputNoOutputJust WorksJust WorksJust WorksJust WorksJust Works
KeyboardDisplayPasskey Entry (I displays, R inputs)Numeric ComparisonPasskey Entry(R displays, I inputs)Just WorksNumeric Comparison

If a device has application-specific security requirements (flags parameter is not 0), the used pairing method and security level of the connection will be different.

MITM - bit 0

Setting the bit 0 forces the MITM protection, which means that our devices will not bond with devices which don't have the I/O capabilities at least for legacy pairing.

Encryption - bit 1

Setting the bit 1 forces link encryption, which means that our devices will always use encrypted link with bonded devices. Note if the bonding table is full, the device can't save the new bond.

LE Secure connections support - bit 2

If both devices support LE Secure Connections, the value of bit 2 doesn’t matter. If either one of the devices doesn’t support secure connections i.e., it supports legacy pairing only, bit 2 comes into play.

If bit 2 is set to 1, the secure connection is enforced and the pairing attempt will fail with an error code 0x303 (pairing_fail_authentication_requirements error). This is essentially saying that the device will not pair with legacy devices. If bit 2 is set to 0, the pairing will fall back to legacy pairing methods.

Application level confirmation of bonding request - bit 3

If bit 3 is set, bonding requests need to also be confirmed by the application. This feature gives additional control over incoming bond requests and the application can reject devices which otherwise could bond. The application is notified about the received bonding request by the sm_confirm_bonding stack event.

The application will either accept or reject the bonding request with the cmd_sm_bonding_confirm command.

Set up Bonding (Enabled/Disabled/Deleted)

To enable secure connection (Security Level 2 and above) the application needs to allow bonding. The stack provides the gecko_cmd_sm_set_bondable_mode API function to enable or disable bonding.

Note if gecko_cmd_sm_configure(flags, io_capabilities) is called with flags parameter, where bit 1 is set, bonding is enabled automatically.

During application development, sometimes it is useful to delete all the bondings to trigger and test the pairing processes. It can be done by the cmd_sm_delete_bondings API.

Use cases when the application has to manage the bonding table directly are out of scope of this document.

Bluetooth SDK v2.4 introduced a new bond replacement algorithm which makes bonding process smarter. There is only limited amount of flash reserved for storing bonds and the new algorithm uses it more efficiently in order to decrease unnecessary flash writes.

Using the new algorithm, bonded devices are stored in a list which is divided into two parts: active bondings and inactive bondings. At the picture below active bondings are marked with green and inactive bondings are marked with red.

The working principle of new algorithm is shown in the picture above and it is based on three rules.

The new bond replacement algorithm does not require intervention from the application. The size of the inactive bondings list is 1/3 of the maximum number of bondable devices rounded up. The maximum number of bondable devices is configured with the max_bonding_count parameter in sm_store_bonding_configuration command.

To enable this new algorithm, you need to use gecko_cmd_sm_store_bonding_configuration(uint8 max_bonding_count, uint8 policy_flags) command and change policy_flags value to 2. Note that you need SDK version 2.4.0 or later.

Increase Security Level

If the GATT attribute permissions are set correctly, the application doesn't have to increase the security level manually. The security level of the connection will be increased after there is access demand for GATT elements which requires higher-security level. If the 2 devices not bonded yet the pairing process also triggered.

However, there can be use cases where the application handles the security level of the connections. In those cases, it makes sense to call the cmd_sm_increase_security API function in the evt_le_connection_opened event handler.

Handle Security Manager Stack Events by the Application

During the pairing process there are few stack events that the application has to handle otherwise the pairing and bonding will fail. These events are the following.

evt_sm_passkey_display: this event indicates a stack request to display the passkey to the user during the pairing process. The application writes the passkey to a display given by the event as a passkey parameter. This event only can happen if the device has a display. It is defined in its I/O capabilities. See the Setting up the security manager section above.

evt_sm_passkey_request: this event indicates a request for the user to enter the passkey displayed on the remote device. The application has to read the passkey then push it to stack by the sm_enter_passkey command.

If the passkey is valid and the bonding is completed, the stack raises a evt_sm_bonded event. If the passkey is invalid or the bonding has failed because for any other reason, the stack will raise an evt_sm_bonding_failed event.

evt_sm_confirm_passkey: this event can happen when the stack is using numeric comparison pairing method. It indicates a request to display the passkey to the user then asks to confirm that the displayed passkey matches the passkey displayed on the remote device. The cmd_sm_passkey_confirm has to be called by the application to accept or reject the displayed passkey depending on the user answer.

evt_sm_bonded: this event is triggered after the pairing or bonding procedure has been successfully completed.

evt_sm_confirm_bonding: this event indicates that new bonding request has been received. The application has to call sm_bonding_confirm to accept or reject the incoming bonding request. This feature can be activated by calling the gecko_cmd_sm_configure(flags, io_capabilities) where the bit 2 of the flag parameter is set to 1.

evt_sm_bonding_failed: this event is triggered when the pairing or bonding procedure has failed. The possible reasons and error codes are documented here.

References

Bluetooth Core Specification

Pairing Processes

Secure Connection Example