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:

• Passive eavesdropping

• Active eavesdropping = Man in the Middle (MITM)

• Privacy (tracking)

Bluetooth defines 5 distinct security features against these threats:

• Pairing — creating trusted relationships between devices (Key Generation, Key Exchange, Identity Information Exchange)

• Bonding — Storing the keys created during pairing for later connections

• Device authentication — verification that devices have the same keys (Protected from MITM)

• Encryption — data confidentiality (FIPS or NIST approved AES128-CCM algorithm used)

• Data signing (Message integrity) — protection against data alteration

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

Pairing#

• The process of creating trusted relationships between devices

• Used to generate and exchange security keys

• Used to exchange identity information

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.

• Just works — For devices without UI. No user interaction required. No MITM protection. In case of Just works pairing there is no possibility to confirm the identity of the connecting devices. Devices will pair with encryption but without authentication.

• Passkey entry — User needs to enter a passkey the remote party displays. Provides MITM protection

• Numeric comparison — User needs to confirm passkeys both devices display. Provides MITM protection

• Out-of-band — Encryption keys exchanged for example with NFC

More details can be found in Pairing Processes post.

Bonding#

• Storing security keys for future use

• ex. authentication of connections or verifying devices identity

Authentication#

• Authentication is defined as a way to prove that the device with which you are connecting is actually the device it claims to be and not a third-party attacker.

• Authentication in the GATT Profile is applied to each characteristic independently. The GATT Profile procedures are used to access information that may require the client to be authenticated.

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#

• Encryption protects the data confidentiality and integrity

• Paired or bonded devices can encrypt/decrypt data sent within a connection

• Bluetooth uses AES-128 as the encryption algorithm

Notice: No encryption of broadcast data

Attribute Permissions#

• Attributes have a set of permissions that controls whether they can be read or written, or whether the attribute value will be sent over an encrypted link.

• Attribute permissions are used by the server to determine whether read or write access is permitted for a given attribute.

• Attribute permissions are established by the GATT Profile so different permissions can be granted for the characteristics and descriptors.

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.

Privacy#

• Bluetooth provides privacy protection

• Devices can either use public or private (random) addresses

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#

• New LE Secure connections feature using Elliptic Curve Diffie-Hellman (ECDH) public-private key pairs for numeric comparison paring method

• New numeric comparison paring method. In this pairing method both devices will display a 6-digit passkey. The user must confirm that the two devices display the same passkey by pressing a button.

• Passkey entry and OOB has updated LE Secure Connection variant. But there is no change from application perspective.

• LE privacy 1.2 — Identity resolving moved from host to controller for faster and lower power operation

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.

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:

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:

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

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.

• When new bonding is created, it is added top of the bondings list. If list is full, then last bonding is dropped out of the list.

• When connection is opened and if device is in inactive bonding list, it is moved on top of the active bondings list. If device is in active bondings list no actions is done.

• When list is updated it is saved into flash.

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.

• max_bonding: the maximum number of bonds saved in the peripheral storage storage and it can have values from 1-14.

• policy_flags: defines bonding mode. The following modes are available:

  • 0: if database is full, new bonding attempts will fail

  • 1: new bonding will overwrite the oldest existing bonding

  • 2: new bonding will overwrite longest time ago used existingbonding (this is The New Bond Replacement Algorithm available in SDK 2.4.0 and above)

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](<docspace-docleaf-version>/bluetooth-error-codes).

References#

Bluetooth Core Specification

Pairing Processes

Secure Connection Example