You are viewing documentation for version: 3.1 | This version works with Simplicity Studio 5 only. If you have Simplicity Studio 4, switch to 2.13. For extended documentation (User’s Guides, Code Examples) also switch to 2.13. | For additional versions, see Version History

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. However, there is no change from the 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, do the following:

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 characteristic's access properties and its permission levels are defined in gatt.xml by the children attributes of the XML attribute, which must be used inside the XML attribute tags. A characteristic can have multiple access properties at the same time. For example, it can be readable, writable, or both. Each access property can have a different permission level (for example, encrypted or authenticated).

These properties can be easily configured with the Bluetooth GATT Configurator for each characteristics:

Access Properties and Permission Levels

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 an encrypted link. Any GATT client can read or write it.

Example 2 — Encrypted Write

The characteristic is now set up differently.

In this case, 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 when just works pairing is used. Writing this characteristic the first time will trigger the pairing process.

Setting up the Security Manager

The application uses the sl_bt_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 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 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 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 the 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 becomes relevant.

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 sl_bt_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 sl_bt_sm_set_bondable_mode() API function to enable or disable bonding.

Note if sl_bt_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 bondings to trigger and test the pairing processes. It can be done by the sl_bt_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. Only a limited amount of flash is reserved for storing bonds and the new algorithm uses it more efficiently to decrease unnecessary flash writes.

Using the new algorithm, bonded devices are stored in a list which is divided into active bondings and inactive bondings. In the image below, active bondings are green and inactive bondings are red.

The working principle of the new algorithm is shown in the image above and it is based on three rules, as follows.

• When the new bonding is created, it is added at the top of the bondings list. If the list is full, the last bonding is dropped out of the list.
• When the connection is opened and if the device is in the inactive bonding list, it is moved to the top of the active bondings list. If the device is in active bondings list, no action is taken.
• When list is updated, it is saved to 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 sl_bt_sm_store_bonding_configuration command.

To enable the new algorithm, use sl_bt_sm_store_bonding_configuration(uint8 max_bonding_count, uint8 policy_flags) command and change policy_flags value to 2.

• max_bonding: the maximum number of bonds saved in the peripheral storage, which 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 the existing bonding, which has not been in use the longest. The New Bond Replacement Algorithm is 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 access demand for GATT elements, which requires a higher-security level. If the two devices are not bonded yet, the pairing process will be also triggered.

However, in some use cases, the application handles the security level of the connections. In those use cases, it makes sense to call the sl_bt_sm_increase_security() API function in the connection_opened event handler to request encryption/authentication on the connection.

Handle Security Manager Stack Events by the Application

During the pairing process, the application has to handle a few stack events. Otherwise, the pairing and bonding will fail. These events are the following:

sl_bt_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 can happen only if the device has a display. It is defined in its I/O capabilities. See the Setting up the security manager section above.

sl_bt_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 sl_bt_sm_enter_passkey() command.

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

sl_bt_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 sl_bt_sm_passkey_confirm() has to be called by the application to accept or reject the displayed passkey depending on the user answer.

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

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

sl_bt_evt_sm_bonding_failed: this event is triggered when the pairing or bonding procedure has failed. The possible reasons and error codes are documented on the Error Codes page.

References

Bluetooth Core Specification

Pairing Processes

Secure Connection Example