Using Bluetooth security features in Silicon Labs Bluetooth SDK
This article 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 implemented in different layers of the Bluetooth stack. Let's have a quick look on these.
Pairing
Is 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
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 shall 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.
Security Level
Description
Level 1
No security
Level 2
Unauthenticated pairing with encryption (paired with just work method)
Level 3
Authenticated pairing with encryption (paired with legacy pairing)
Level 4
Authenticated Secure Connections pairing with encryption using a 128-bit strength encryption key (Paired with LE secure pairing which is Bluetooth 4.2 feature)
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:
Set up attribute permissions in GATT
Set up security manager
Set up bonding (enabled/disable/delete)
Increase security level (optional)
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 property
description
read
Characteristic can be read by a remote device
write
Characteristic can be written by a remote device
bonded_read
Reading the characteristic value requires an encrypted link. Devices must also be bonded at least with Just Works pairing
bonded_write
Writing the characteristic value requires an encrypted link. Devices must also be bonded at least with Just Works pairing
authenticated_read
Reading the characteristic value requires an authentication. In order 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_write
Writing the characteristic value requires an authentication. In order 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_read
Reading the characteristic value requires an encrypted link. iOS 9.1 and newer devices must also be bonded
encrypted_write
Writing the characteristic value requires an encrypted link. iOS 9.1 and newer devices must also be bonded
GATT Examples
Here we have 3 example 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
In this case reading the characteristic is without any restriction. But writing the characteristic requires encrypted link. Characteristics which requires encryption cannot be accessed without pairing. So writing this characteristic in the first time will trigger the pairing process. The pairing can be just works so it is allowed to not have MITM protection.
Example 3 — Authenticated write
Now let's modify the characteristic properties again.
In this case reading the reading the characteristic is without any restriction. But writing requires authentication. It means the remote device must be bonded with man in the middle (MITM) protection enabled. So 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 shall use the gecko_cmd_sm_configure(flags, io_capabilities) API to set up the security configuration. The io_capabilities and flagsparameters affect the security level with which the devices will use in connection and leads 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:
Value
Enumeration
Description
0
sm_io_capability_displayonly
Display Only
1
sm_io_capability_displayyesno
Display with Yes/No-buttons
2
sm_io_capability_keyboardonly
Keyboard Only
3
sm_io_capability_noinputnooutput
No Input and No Output
4
sm_io_capability_keyboarddisplay
Display with Keyboard
The flags parameter controls different application specific security requirements. This parameter gives flexibility to the application to decide how strictly use or not use at all the Bluetooth security features. The table below shows the different options:
Bitmask
Description
bit 0
0: Allow bonding without MITM protection
1: Bonding requires MITM protection
bit 1
0: Allow encryption without bonding
1: Encryption requires bonding. Note that this setting will also enable bonding.
bit 2
0: Allow bonding with legacy pairing
1: Secure connections only
bit 3
0: 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 4 to 7
Reserved
If the flags parameter is 0, so no application specific requirement set, the pairing method depends only on the IO capabilities of the initiator and the responder device (shown as I and R on the table below).
Responder/Initiator IO capabilities
Display Only
DisplayYesNo
KeyboardOnly
NoInputNoOutput
KeyboardDisplay
Display only
Just Works
Just Works
Passkey Entry(R displays,I inputs)
Just Works
Passkey Entry (R displays,I inputs)
DisplayYesNo
Just Works
Numeric Comparison
Passkey Entry (R displays, I inputs)
Just Works
Numeric Comparison
KeyboardOnly
Passkey Entry (I displays, R inputs)
Passkey Entry (I displays, R inputs)
Passkey Entry (R and I inputs)
Just Works
Passkey Entry(I displays, R inputs)
NoInputNoOutput
Just Works
Just Works
Just Works
Just Works
Just Works
KeyboardDisplay
Passkey Entry (I displays, R inputs)
Numeric Comparison
Passkey Entry(R displays, I inputs)
Just Works
Numeric Comparison
If a device has application specific security requirements (flags parameter is not 0) then the used pairing method and security level of the connection will be different.
MITM - bit 0
Setting the bit 0 forces the MITM protection. In practice it means that our devices will not bond with devices which don't have the io capabilities at least for legacy pairing.
Encryption - bit 1
Setting the bit 1 forces link encryption. In practice it means that our devices will always use encrypted link with bonded devices. Note if the bonding table is full therefore the device can't save the new bond.
LE Secure connections support - bit 2
If both devices support LE Secure Connections, then the value of then bit 2 doesn’t matter. If either one of the devices doesn’t support secure connections i.e. it supports legacy pairing only, then bit 2 comes into play.
If bit 2 set to 1, secure connection is enforced, and the pairing attempt will fail with error code 0x303 (pairing_fail_authentication_requirements error). This is essentially saying that we don’t want to pair with legacy devices. If bit 2 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 then bonding requests need to be confirmed by the application too. This feature gives additional control over incoming bond requests. So the application can reject devices which otherwise could bond. The application notified about the received bonding request by the sm_confirm_bondingstack event.
The application shall accept or reject the bonding request with the cmd_sm_bonding_confirm command.
Set up bonding (enabled/disable/delete)
To enable secure connection (Security Level 2 and above) the application need to allow bonding. The stack provides the gecko_cmd_sm_set_bondable_mode API function to enable or disable the bonding.
Please note if gecko_cmd_sm_configure(flags, io_capabilities) called with flags parameter where bit 1 is set then the bonding 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.
There are use cases when the application has to manage the bonding table directly. This is out of scope of this article. You can read more about this in a separate KBA.
Increase security level
If the GATT attribute permissions are set correctly the application don't have to increase the security level manually. The security level of the connection will be increased once 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
The evt_sm_passkey_display event indicates a request by stack to display the passkey to the user during the pairing process. The application shall write the passkey to a display given by the event as passkey parameter. This event only can happen if the device has a display. It is defined in its io capabilities. See [the Setting up the security manager](### Setting up the security manager) chapter above.
evt_sm_passkey_request
The evt_sm_passkey_request 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 was valid and the bonding completed the stack raise a evt_sm_bonded event. If the passkey was invalid or the bonding failed because of any other reason the stack will raise a evt_sm_bonding_failed event.
evt_sm_confirm_passkey
This event can happen when the stack is using numeric comparison pairing method. Its indicates a request to display the passkey to the user then asks to confirm that displayed passkey is the same what is 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 users 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 failed. The possible reasons and errorcodes are documented here.
Hi
Please correct me if I misunderstood, this article is for device acting as a BLE server, right?
What if it is the other way around? If my device is acting as a BLE client while my mobile app is acting like a BLE server, how to authenticate the connection and encrypt data transmission?
It seems like the server side should be setting up the security measure, but I didn't see security features after some quick searches... or perhaps I didn't search in the right place?
Specifically, my application is following this example. Would it be possible to add security measure? https://www.silabs.com/community/wireless/bluetooth/knowledge-base.topic.10.10.html/ble_central_and_gatt-7cNE
Thanks,
Dennis
0
Hi Dennis,
I am in the same page as you, what if before connecting my mobile app with the board, I need to enter a password in the app side for the board with which I want to get it connceted
[Deprecated] KBA_BT_1101: Using Bluetooth security features in Silicon Labs Bluetooth SDK
Note: This KBA has been marked as deprecated. A more updated KBA can be found here: Using Bluetooth Security Features in Silicon Labs Bluetooth SDK
Using Bluetooth security features in Silicon Labs Bluetooth SDK
This article 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 implemented in different layers of the Bluetooth stack. Let's have a quick look on these.
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 here in the Pairing Processes KBA.
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.
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
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:
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
Here we have 3 example 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
In this case reading the characteristic is without any restriction. But writing the characteristic requires encrypted link. Characteristics which requires encryption cannot be accessed without pairing. So writing this characteristic in the first time will trigger the pairing process. The pairing can be just works so it is allowed to not have MITM protection.
Example 3 — Authenticated write
Now let's modify the characteristic properties again.
In this case reading the reading the characteristic is without any restriction. But writing requires authentication. It means the remote device must be bonded with man in the middle (MITM) protection enabled. So 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 shall use the gecko_cmd_sm_configure(flags, io_capabilities) API to set up the security configuration. The io_capabilities and flagsparameters affect the security level with which the devices will use in connection and leads 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 use or not use at all the Bluetooth security features. The table below shows the different options:
If the flags parameter is 0, so no application specific requirement set, the pairing method depends only on the IO 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) then the used pairing method and security level of the connection will be different.
MITM - bit 0
Setting the bit 0 forces the MITM protection. In practice it means that our devices will not bond with devices which don't have the io capabilities at least for legacy pairing.
Encryption - bit 1
Setting the bit 1 forces link encryption. In practice it means that our devices will always use encrypted link with bonded devices. Note if the bonding table is full therefore the device can't save the new bond.
LE Secure connections support - bit 2
If both devices support LE Secure Connections, then the value of then bit 2 doesn’t matter. If either one of the devices doesn’t support secure connections i.e. it supports legacy pairing only, then bit 2 comes into play.
If bit 2 set to 1, secure connection is enforced, and the pairing attempt will fail with error code 0x303 (pairing_fail_authentication_requirements error). This is essentially saying that we don’t want to pair with legacy devices. If bit 2 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 then bonding requests need to be confirmed by the application too. This feature gives additional control over incoming bond requests. So the application can reject devices which otherwise could bond. The application notified about the received bonding request by the sm_confirm_bondingstack event.
The application shall accept or reject the bonding request with the cmd_sm_bonding_confirm command.
Set up bonding (enabled/disable/delete)
To enable secure connection (Security Level 2 and above) the application need to allow bonding. The stack provides the gecko_cmd_sm_set_bondable_mode API function to enable or disable the bonding.
Please note if gecko_cmd_sm_configure(flags, io_capabilities) called with flags parameter where bit 1 is set then the bonding 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.
There are use cases when the application has to manage the bonding table directly. This is out of scope of this article. You can read more about this in a separate KBA.
Increase security level
If the GATT attribute permissions are set correctly the application don't have to increase the security level manually. The security level of the connection will be increased once 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
The evt_sm_passkey_display event indicates a request by stack to display the passkey to the user during the pairing process. The application shall write the passkey to a display given by the event as passkey parameter. This event only can happen if the device has a display. It is defined in its io capabilities. See [the Setting up the security manager](### Setting up the security manager) chapter above.
evt_sm_passkey_request
The evt_sm_passkey_request 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 was valid and the bonding completed the stack raise a evt_sm_bonded event. If the passkey was invalid or the bonding failed because of any other reason the stack will raise a evt_sm_bonding_failed event.
evt_sm_confirm_passkey
This event can happen when the stack is using numeric comparison pairing method. Its indicates a request to display the passkey to the user then asks to confirm that displayed passkey is the same what is 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 users 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 failed. The possible reasons and errorcodes are documented here.
References
API Documentation
Bluetooth Core Specification
Pairing Processes
Application Layer Security
Bond Replacing Algorithm
OOB Introduction
Secure Connection Example
Authenticating Devices with No User Interface
Hi
Please correct me if I misunderstood, this article is for device acting as a BLE server, right?
What if it is the other way around? If my device is acting as a BLE client while my mobile app is acting like a BLE server, how to authenticate the connection and encrypt data transmission?
It seems like the server side should be setting up the security measure, but I didn't see security features after some quick searches... or perhaps I didn't search in the right place?
Specifically, my application is following this example. Would it be possible to add security measure?
https://www.silabs.com/community/wireless/bluetooth/knowledge-base.topic.10.10.html/ble_central_and_gatt-7cNE
Thanks,
Dennis
Hi Dennis,
I am in the same page as you, what if before connecting my mobile app with the board, I need to enter a password in the app side for the board with which I want to get it connceted