Security
BLE Security Overview
The primary BLE services provided by Bluetooth Xpress modules are always encrypted for privacy. To use either the Xpress Streaming Service or the OTA firmware update service, connecting devices must complete a pairing procedure to allow encryption.
Bluetooth Xpress modules support Security Mode 1 (encryption) Levels 2, 3 and 4:
- Level 2 : Unauthenticated "Just works" encryption with no passkey
- Level 3 : Authenticated encryption with a passkey
- Level 4 : Authenticated LE Secure Connections pairing with encryption
Note : Level 1 "No encryption" is not supported for the BGX primary BLE services.
Bluetooth Xpress module BLE encryption and pairing are managed by three encryption variables:
Pairing Methods
Bluetooth Xpress modules provide support for two pairing method types. These are selected by setting the encryption key variable ( bl e k ):
- "Just Works" (keyless - unauthenticated)
- 6 digit pin code (passkey - authenticated)
Legacy Pairing and Secure Connections
Bluetooth Xpress supports both LE Legacy Pairing (pre 4.2) and LE Secure Connections (4.2 or newer). The variable ( bl e p ) can be used to disable support for LE Legacy Pairing if desired.
LE Secure Connections
provides the highest level of security. For use cases
that do not require legacy support (such as BGX to BGX), it is recommended to
set (
bl e p
) =
secure
in order to disable LE Legacy
Pairing. However,
support for LE Secure Connections is not universal among
phones
, so setting (
bl e p
) =
any
will support the
widest range of phones.
Disabling Pairing
Starting with firmware version
1.1.1229.0
, setting the variable
(
bl e p
) =
off
disables all new pairing requests.
Devices that had previously paired and bonded (see next topic) with the
Bluetooth Xpress module will still be able to connect and use the encrypted
services, but all new devices will not. This provides additional control
over which devices may use the module's services.
For an example that uses
bl e p
configuration at run time to only support
pairing with allowed devices, see the
BGX-to-BGX Example
.
Bonding and Pairing
Bluetooth Xpress is designed to simplify the use of Bluetooth in an application and reduce the need for detailed technical understanding of Bluetooth. However, because Bluetooth connections can fail for a number of reasons, it helps to understand the meaning of pairing and bonding.
Simply put, pairing is the exchange of encryption keys that will be used for encrypting a connection between devices.
Bonding is storing the keys that are used for pairing so that they can easily reconnect.
These two terms are often used interchangeably which can add confusion. Also, many phones will remember devices even if they have not bonded which can also cause problems.
Bluetooth Xpress and Bonding
Bluetooth Xpress modules provide support for bonding, which is configured using the variable ( bl e b ). When bonding is enabled the Bluetooth Xpress modules will remember the pairing information from each new device connection, so that the pairing procedure is not performed on subsequent connections with that device.
Number of bonded devices: Up to 14 devices can be stored in the BGX internal bonding table. After 14 devices have been stored, new bonds will overwrite the bond in the bonding table that has not been used in the longest amount of time. Therefore, new devices can always be bonded, but it will remember a maximum of 14, and less used devices are forgotten as new devices are added.
For bonding to work correctly
both devices in a new connection must agree
to bond. Many phones assume bonding is always enabled, so for use cases where
Bluetooth Xpress is communicating with a mobile device, it is recommended to
set (
bl e b
) =
1
.
The table below provides details of the available systems.
References are to Specification of the Bluetooth System , core package version 5.0. See https://www.bluetooth.org .
Key
bl e k |
Advantages | Disadvantages | Use Case | BLE pairing procedure | BLE security mode |
---|---|---|---|---|---|
none | Simplest to use, just works with a range of devices | Does not protect against "Man in the Middle" attack | When the other device has no IO capabilities to enter a pin code or when the user is not concerned about "Man in the Middle" attack | Just Works Procedure (Vol 3, Part H, 2.3.5.2) |
bl e p any
Mode 1 Level 2.
bl e p secure
Mode 1 Level 4. |
6 digit pin code | Gives better protection, works best with smart phones | A 6 digit key is vulnerable to a brute force attack. | When the other device has pin code input capabilities, such as a smart phone | Pass key entry Procedure (Vol 3, Part H, 2.3.5.3) |
bl e p any
Mode 1 Level 3.
bl e p secure
Mode 1 Level 4. |
Remote Access Restrictions
Beginning with version
1.2.2045.0
, several new security features were added
to allow restrictions on remote access. The following features provide
restrictions to remote access:
Remote Restricted Mode
The variable sy r e can be used to restrict access to the remote command interface. Remote access can be:
- disabled - the command interface can only be used from the serial UART connection
- enabled - the command interface can be used remotely from a connected device
- restricted - a limited subset of remote commands are available
Using restricted mode allows an application to perform remote operation such as changing GPIO or using the I2C bus, while not allowing any configuration changes.
Remote Access Password
The variable sy r p can be used to require a password for remote COMMAND access. If a password is set, then it must be provided to place the BGX into remote command mode using the rbmode command or the Xpress Streaming Service mode characteristic.
OTA Update Password
The variable sy o p can be used to require a password in order to perform an over-the-air (OTA) firmware update. The password must be provided by the BGXpress Framework when performing an OTA firmware update.
Deployment Security Considerations
Bluetooth Xpress has several settings that affect device security. By default, any device can establish a connection and use Remote COMMAND Mode to alter the device settings. By default there is also no restriction on loading a new or different version of BGX firmware via Bluetooth OTA. If the end product using BGX will be deployed in a controlled environment, then the default settings are probably safe. However, if the product is deployed where it is publicly accessible, then it may be necessary to change some default settings to make the device more secure.
The following settings can affect device security:
-
bl e k
- this is set to
none
by default which means any device can connect (anyone can use their mobile phone to connect). If this setting is changed to a 6-digit PIN code, then only someone who knows the PIN code can connect to the device. - bl e p - this can be used to disable pairing once allowed devices have paired with Bluetooth Xpress. Once disabled then no new devices will be allowed to pair. See also Disabling Pairing .
- sy r e - this allows remote commanding of the device. This means that once connected, another device can send commands and change settings. If this setting is disabled, then a connected device is prevented from sending commands or changing any settings. If this setting is restricted then a connected device can use some remote command but cannot change the configuration of the device.
- sy r p - this allows requiring a password for remote command access
- sy o e - this allows Bluetooth Xpress firmware to be loaded onto the device via Bluetooth OTA. This means that a connected device is able to load a different version (newer or older) onto the BGX. If this is disabled then the firmware can not be updated.
- sy o p - this allows requiring a password for OTA firmware updates
Note about "connecting"
In the section above, the term "connecting" is used to mean "establish a Bluetooth connection and use the device services". Any Bluetooth device can establish a connection with a BGX that is advertising, but using the BGX streaming and OTA services also requires that the device pairs as determined by the security settings. Therefore, without pairing it is effectively "not connected" from a functional point of view.
Solving Connection Problems
Due to the complexity of this topic and inconsistent implementations by device vendors, connection problems may occur when trying to connect BGX and another device such as a mobile phone. Connection problems can also occur between BGX-to-BGX connections if device settings are incompatible.
The most likely reasons why you may encounter a problem when connecting to a BGX are:
- Stale bonding data in one device
- Mobile device only supports legacy pairing
- BGX-to-BGX: both devices do not have the same settings
Here are some ways you can tell there is a connection problem:
-
you see a
BOND_FAIL
message on the BGX terminal console - BGX Commander shows you a message about insufficient encryption
(See also Error Codes below.)
Stale Bonding Data
Stale bonding data means that one device of a pair (BGX and BGX, or BGX and mobile phone) has stored bonding data and the other has not. This happens when devices that were previously bonded have been changed so that one of them no longer holds bonding data. This could happen for the following reasons:
-
clrb
(clear bonding) command has been issued to the BGX -
fac
(factory reset) command has been issued to BGX - mobile device was commanded by user to "forget" the BGX device
- mobile device incorrectly implements storage of bonding data
Solution
When a BGX-to-BGX or phone-to-BGX connection fails due to stale data, it can almost always be resolved by clearing bonding data on both devices.
-
BGX: issue
clrb
command on a terminal -
phone: instruct phone to
forget
the BGX device
After you clear the bonding data on both devices, they should be able to connect.
Legacy Pairing
Bluetooth Xpress supports both
LE Secure Connections
and
LE Legacy Pairing
.
Some older mobile devices only support the legacy method. In order to work with
these devices the BGX must be configured to allow legacy pairing. This feature
is controlled by the variable
bl e p
. Prior to firmware
version
1.1.1229.0
, the factory setting for this variable was
secure
which
enforces secure connections.
Solution
Use a terminal or Xpress Configurator to change the value of the
bl e p
variable from
secure
to
any
. Then re-attempt the connection. You may
need to also clear stale bonding data (see above).
BGX-to-BGX
When using a BGX-to-BGX connection, the following variables must be set the same on both devices in order to establish a connection. If you are having a problem with a BGX-to-BGX connection, verify the following settings match.
Error Codes
The following table shows error codes that may appear when establishing a connection with BGX, and possible recovery steps.
See also Solving Connection Problems above.
Code | Cause / Recovery |
---|---|
0206
pin_or_key_missing |
Cause:
Devices were previously bonded but bond was cleared on the BGX peripheral
Recovery: clear the previous bond on BGX central or the mobile device |
0303
authentication_requirements |
Cause
: One BGX device has 'bl e k none' while the other has a passcode set
Recovery: ensure that both devices have the same value for 'bl e k' Cause: BGX peripheral is set to 'bl e p secure' but the mobile device only supports legacy pairing. Error is shown on BGX peripheral Recovery: change the setting of 'bl e p' to "any" |
0304
confirm_value_failed |
Cause:
BGX devices have different passkeys, or the mobile device entered the wrong passkey
Recovery: ensure that the passcode setting 'bl e k' is correct |
0305
pairing_not_supported |
Cause:
BGX peripheral has disabled pairing ('bl e p off') and the devices were not previously bonded. Error is shown only on BGX central
Recovery: set 'bl e p' to "any" so that devices can be paired, and then set 'bl e p' to "off" once devices are paired |