Using Bluetooth Security Features in Silicon Labs Bluetooth SDK


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.


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.



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.


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)


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

Access PropertyPermission LevelDescription
readCharacteristic can be read by a remote device
writeCharacteristic can be written by a remote device
readbondedReading the characteristic value requires an encrypted link. Devices must also be bonded at least with Just Works pairing
writebondedWriting the characteristic value requires an encrypted link. Devices must also be bonded at least with Just Works pairing
readauthenticatedReading 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
writeauthenticatedWriting 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
readencryptedReading the characteristic value requires an encrypted link. iOS 9.1 and newer devices must also be bonded
writeencryptedWriting the characteristic value requires an encrypted link. iOS 9.1 and newer devices must also be bonded

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:

0sl_bt_sm_io_capability_displayonlyDisplay Only
1sl_bt_sm_io_capability_displayyesnoDisplay with Yes/No-buttons
2sl_bt_sm_io_capability_keyboardonlyKeyboard Only
3sl_bt_sm_io_capability_noinputnooutputNo Input and No Output
4sl_bt_sm_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 the Bluetooth security features. The table below shows the different options:

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

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.

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.


Bluetooth Core Specification

Pairing Processes

Secure Connection Example