Security Handling in Hardware and Software#

Overview#

BG22 devices feature a Cryptographic Accelerator peripheral that helps meet the speed and energy demands of secure applications while providing additional protection against common attacks. You will take a look at unencrypted messages and secure BLE connections with Network Analyzer. Then, the lab also includes hands on experience working with the security features by creating a Bluetooth beacon application that uses the PSA Crypto API to encrypt custom advertisement data.

Getting Started#

Ensure that you have the correct hardware and software prepared to successfully complete the lab.

Prerequisites#

For this lab you will need the following:

• EFR32BG22 Thunderboard (SLTB010A)

• Micro-USB to USB Type-A cable, which is not a power cable. This cable is not included with Thunderboard. It must include data lines.

• Simplicity Studio v5

  • Gecko SDK Suite 3.2.0 or later

  • Bluetooth SDK 3.2.0 or later

• EFR Connect Mobile App

  • Accept Location Access. “While using the App” will work. This is required for the Traffic Browser.

Download the Workshop Source Files#

• app.c

Set up Thunderboard Kit and Simplicity Studio#

1. Launch Simplicity Studio from your desktop.

2. Connect the Thunderboard BG22 to your PC using a micro-USB cable.

3. When the device is connected to your PC, you should see it listed in the Debug Adapters window in Simplicity Studio.

4. Select the J-link for the device to display the associated Overview, Example Projects, Documentation, and Demos.

5. Set the preferred SDK to Gecko SDK Suite v3.2.0 or newer.

6. Ensure that the Secure Firmware Version is the latest one. Read and Update if not displayed.

7. Ensure your device has a bootloader installed. You can install a bootloader by flashing a demo example, such as the SoC-empty demo in the Example projects & Demo’s tab or by creating a bootloader project, such as the BGAPI UART DFU Bootloader, generating the code, and then building and flashing the bootloader image. For a more detailed explanation, see How to Use Bootloaders and OTA in Your Project.

CRYPTOACC Peripheral#

Efficient hardware-based cryptography helps to meet the speed and energy demands of secure applications while providing additional protection against common attacks. There are a number of benefits to accelerating cryptographic operations in hardware:

• Faster execution

• More energy efficient

• Offloads the main core

• Saves code space

• More resistant to differential power analysis (DPA) attacks

The EFR32xG22 devices incorporate the CRYPTOACC peripheral for cryptographic hardware acceleration. The CRYPTO module provides an efficient acceleration of common cryptographic operations and allows these to be used efficiently with low CPU overhead. The CRYPTO module includes hardware accelerators for the Advanced Encryption Standard (AES), Secure Hash Algorithm SHA-1 and SHA-2 (SHA-224 and SHA-256), and modular multiplication used in ECC (Elliptic Curve Cryptography) and GCM (Galois Counter Mode). The CRYPTO module can autonomously execute and iterate a sequence of instructions to aid software and speed up complex cryptographic functions like ECC, GCM, and CCM (Counter with CBC-MAC).

mbedTLS and PSA Crypto#

In addition to the CRYPTO module, Silicon Labs includes mbedTLS as part of the Gecko Platform SDK. mbed TLS is open source software licensed by ARM Limited. It provides an SSL library that makes it easy to use cryptography and SSL/TLS in applications. The PSA Crypto API is a low-level cryptographic API optimized for MCU and Wireless SoC. It provides APIs related to Random Number Generation (RNG), cryptographic algorithm usage, and key handling (symmetric and asymmetric). The PSA Crypto API provides developers with an easy-to-use and easy-to-learn interface to crypto primitives. It is designed for usability and flexibility and is based on the idea of a key store.

The PSA Cryptographic API is an important PSA component that provides a portable interface to cryptographic operations on a wide range of hardware. Silicon Labs PSA Crypto implementations support RNG, symmetric and asymmetric keys, message digests, MAC, unauthenticated ciphers, AEAD, KDF, ECDSA, and ECDH. The AN1311: Integrating Crypto Functionality Using PSA Crypto Compared to Mbed TLS application note describes how to integrate crypto functionality into applications using PSA Crypto compared to Mbed TLS.

This standard mbedTLS or PSA API will handle the interface with the CRYPTOACC peripheral. There are several code examples available within Simplicity Studio 5 that provide a starting point for custom applications and illustrate the use of the cryptographic libraries.

Lab#

Run the Thunderboard Demo#

First, lets run the Bluetooth - SoC Thunderboard demo.

1. Open Simplicity Studio v5. If the Thunderboard BG22 has not been plugged in using the USB cable, do so now. The kit and debug information should be displayed in the Debug Adapters window.

2. In the Debug Adapters window, click on the device.

3. Information about the target hardware and software will appear. If this does not appear, click on the Launcher button in the top right corner.

4. Select the Preferred SDK to the latest version. For this lab, the latest version of Gecko SDK (v3.2.0) is used.

5. Click on Example projects & Demo’s tab to browse the example projects.

6. Select “Bluetooth” from the Technology Type filters. Additionally, you can type "Thunderboard" in Keywords to narrow results.

Capture BLE Traffic Using Network Analyzer#

Simplicity Studio® 5 (SSv5)'s Network Analyzer tool captures a trace of wireless network activity. It uses the device’s PTI (Packet Trace Interface) that collects all received and transmitted packets and some meta data directly from the sequencer without affecting normal operation. Any PTI-enabled Silicon Labs platform can record the radio activity regardless of the application firmware that is being used.

To start capturing with Network Analyzer:

1. Right click on the device in the Debug Adapters view and press Connect:

   

2. Right click on the device again and press Start capture.

The Network Analyzer view is automatically opened. You can see radio packets that are listed in the Events tab. By clicking on them, you can see the details and the hex dump of the packet. After starting the capture, you will first see advertisement and scan request packets as the Thunderboard application is a server device. This lab does not use the Transactions tab.

Connect to the Thunderboard Using a Smartphone#

1. Start the EFR Connect app on your phone.

2. Start the Bluetooth Browser.

3. Connect to your device advertising as "Thunderboard".

   

4. Tap on the Device Information service and read out the Model Number String Characteristic.

   

5. Observe this read operation in Network Analyzer. For this, open the Network Analyzer tab in Simplicity Studio. In Network Analyzer, after the connect indication, you can see how connect parameters are negotiated and how the smartphone discovers the GATT database of the Thunderboard application. Empty packets from the client are necessary to keep the connection alive. However, most of the time they can be filtered out for a more transparent trace.

6. To filter out connected empty packets from the trace, you can use the following filter: event.summary != "BLE LL - Empty PDU"

Lets see what happened when you read out a characteristic of the device. In this log, you can see which attribute was read and what was the actual value. It's exactly the same with an external sniffer device, so everyone in the radio range has access to this data.

1. Stop capturing. For this, right click on the device in the Debug Adapters window. After it, close the trace called Live. We don't need to save it now.

Fortunately, BLE supports secure connections. Bluetooth version 4.2 significantly increased the security of the protocol by using the public key-based key exchange. The Bluetooth specification defines security features to protect the user’s data and identity. Now let's secure our connection against passive eavesdroppers. In The Bluetooth LE protocol, it is achievable by pairing.

GATT Permissions#

In the GATT database, different permissions can be granted for characteristics and descriptors. This exercise demonstrates what happens if the client tries to read data with encrypted permission and how the permission can be granted via pairing processes.

A characteristic which requires encryption cannot be accessed without pairing because reading this characteristic requires an encrypted link. Reading this characteristic for the first time will trigger the pairing process. The pairing process depends on the IO capabilities of both client and server devices. Note that in case of "Just Works" pairing, it is not possible to confirm the identity of the connecting devices. Devices will pair with encryption but without authentication.

To protect against passive eavesdropping, LE Secure Connection uses ECDH public key cryptography, which provides a very high degree of strength against passive eavesdropping attacks as it allows the key exchange over unsecured channels. The Bluetooth low energy technology provides multiple options for pairing, depending on the security requirements of the application. Now we are using Just works.

1. Let's create a project that we can modify:

   1. Go to the Launcher view in Simplicity Studio v5. For this, click on the Launcher button in the top right corner.

   2. Click on Create New Project in the upper right hand corner. A "New Project Wizard" window should appear.

   3. For this exercise, the Bluetooth - SoC Thunderboard EFR32BG22 will be used. Under the Technology Type filter window, select the Bluetooth filter option. On the right under the resources list, scroll and select Bluetooth - SoC Thunderboard EFR32BG22 (BRD4184A).

   4. Click Next to move on.

   5. Rename the project. For this lab, name the project sec_workshop_thunderboard.

   6. Select Copy contents to copy the project files into your project. This makes version control easier to manage and future updates to the Simplicity Studio libraries will not impact the copied files in this project. 'Link the SDK and copy project sources' is selected by default. This creates the new project in the Simplicity Studio workspace. It will link any library files from the SDK and copy any source files directly into the project folder.

   7. Click Finish to generate the project.

      

2. Modify the GATT database configuration. In the Project Configurator, the default tab is opened after creating the project or you can open it by double clicking the sec_workshop_thunderboard.slcp. Go to the Software Components tab and browse to Advanced Configurators > Bluetooth GATT Configurator. You will see the button to open on the top right corner when you select the component. Click it.

3. Once in the GATT Configurator, you can set the read property of the Device Information -> Serial Number String characteristic to encrypted with the radio button.

1. Save the configuration (Ctrl+S), which will apply the changes to the GATT database files gatt_db.c and gatt_db.h.

2. Build the project by clicking on the hammer icon, which will generate the application image to be flashed to your device.

3. Flash the application image to your device by going into the project explorer tab. In your project root folder, in a binaries folder, click on the drop down arrow and right click on "sec_workshop_thunderboard.hex" > flash to device.

1. Start capture using Network Analyzer as described in exercise 1.

2. Connect to the device with a smartphone again and read out the Device Information -> Serial Number String characteristic. Read other characteristics as well. If you are using an iOS device, accept the pairing request.

1. Observe the packets in Network Analyzer.

Because the connection is encrypted, you can no longer understand the Bluetooth traffic. Network Analyzer detects it and gives the following error message:

You can only see encrypted BLE packets which is good for the application but during development and debugging, it is important to decrypt these packets in the log. Network Analyzer is capable of decrpyting all the BLE communications if it knows the security keys. You can add the used security key in Simplicity Studio here:

Window -> Preferences -> Network Analyzer -> Decoding -> Security Keys

You can also set debug mode in firmware. In this mode, the secure connections pairing uses known debug keys, so that the encrypted packet can be opened by Bluetooth protocol analyzer. For this reason, pairings made in debug mode are unsecure.

Using Debug Mode#

This exercise uses debug mode to decrypt the encrypted Bluetooth traffic with Network Analyzer. This example will also initiate pairing in a different way.

1. Open the app.c file in the created sec_workshop_thunderboard project.

2. Place the sl_bt_sm_set_debug_mode() command in the beginning of the sl_bt_evt_system_boot_id event.

   

3. Place the sl_bt_sm_increase_security() command in the sl_bt_evt_connection_opened_id event. In this way, pairing is initiated immediately from the server side after connection.

   

4. Build and flash the modified application to the Thunderboard.

5. Start capturing with Network Analyzer.

6. Connect to the device with a smartphone.

As you can see in the Network Analyzer trace, the connection was encrypted but you can get the decrypted messages because of the debug mode.

Bluetooth LE technology uses AES-CCM cryptography for encryption and the encryption is performed by the Bluetooth low energy controller. CCM operating mode is capable of protecting data integrity and confidentiality.

Encrypted Custom Advertisement#

In this exercise you are going to make a beacon application starting from the Bluetooth - SoC Empty example. The PSA Crypto API will be used to encrypt custom advertisement data. The device will advertise a 16 byte long cipher encrypted with AES-ECB mode.

Create Example Project#

1. Go to the Launcher perspective in Simplicity Studio by clicking on the “Launcher” icon on the top right corner. “Launcher” and “Simplicity IDE” options should be visible.

2. Select the J-link device.

3. Click on Example projects & Demo’s tab to browse the example projects.

4. Select “Bluetooth” from the Technology Type filters. Additionally, you can type “Empty” in Keywords to narrow results.

5. Select Bluetooth - SoC Empty from the Bluetooth examples and click Create. (Do not select the "demo").

   

6. Rename the project to sec_workshop_advertisement and press Finish.

Modify the Project#

First, add the log functionality to the application. The Project Configurator tab is opened after creating the project or you can open it by double clicking the .slcp file. Go to the Software Components tab and install the following Software Components:

• Services -> IO Stream -> IO Stream: USART

• Application -> Utility -> Log

After this, copy and overwrite the default app.c in your project with the app.c source file provided by this lab.

Code Explanation#

This section reviews parts of the code that are important to understand this lab exercise. Here is the architectural overview of the security part:

Custom Advertisement#

The device needs to advertise a custom manufacturer-specific data. The Advertising Manufacturer Specific Data software example serves as the basis for this feature. For more information about advertising, see the Bluetooth Advertising Data Basics article document which explains the basics of BLE advertising packet formatting.

Advertising data consists of one or more Advertising Data (AD) elements. This example uses the following elements:

• Flags: mandatory for every advertisement

• Device name

• Custom: manufacturer-specific data

typedef struct{
  uint8_t flags_len;                    // Length of the Flags field
  uint8_t flags_type;                   // Type of the Flags field
  uint8_t flags;                        // Flags
  uint8_t name_len;                     // Length of the Name field
  uint8_t name_type;                    // Type of the Name field
  uint8_t name[ADVERTISING_NAME_SIZE];  // Name
  uint8_t manuf_len;                    // Length of the Manufacturer ID field
  uint8_t manuf_type;                   // Type of the Manufacturer ID field
  uint8_t company_LO;                   // Manufacturer ID lower byte
  uint8_t company_HI;                   // Manufacturer ID higher byte
  uint8_t adv_data[CIPHER_MSG_SIZE];    // User data field
}custom_adv_t;

The advertisement payload is composed. Call the sl_bt_advertiser_set_data() command:

 encrypted_adv_data.flags_len = 0x02;
 encrypted_adv_data.flags_type = 0x01;
 encrypted_adv_data.flags = 0x04 | 0x02;
 encrypted_adv_data.name_len = ADVERTISING_NAME_SIZE+1;
 encrypted_adv_data.name_type = 0x09;
 memcpy(encrypted_adv_data.name, device_name, ADVERTISING_NAME_SIZE);
 encrypted_adv_data.manuf_len = 0x13;
 encrypted_adv_data.manuf_type = 0xFF;
 encrypted_adv_data.company_LO = 0xFF;
 encrypted_adv_data.company_HI = 0x02;
 memcpy(encrypted_adv_data.adv_data, cipher_msg, CIPHER_MSG_SIZE);

 sc = sl_bt_advertiser_set_data(advertising_set_handle,
                                0,
                                sizeof(encrypted_adv_data),
                                (uint8_t *)(&encrypted_adv_data));

Then, start advertising with the advertiser_user_data configuration:

sc = sl_bt_advertiser_start(
     advertising_set_handle,
     advertiser_user_data,
     advertiser_non_connectable);

AES-ECB Encryption#

In PSA Crypto, applications must call psa_crypto_init() to initialize the library before using any other function. However, in this case, the Bluetooth stack has already initialized it so you don’t need to. In the application, the aes_ecb_encrypt_message() function is responsible for encrypting the given plain message.

In this example, the default sample data and AES key:

// Plain message: 000102030405060708090a0b0c0d0e0f
static uint8_t plain_msg[PLAIN_MSG_SIZE] = {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f};

// AES key: 91f71618e4e8cbf4979f4e613fcbfb50
static uint8_t aes_key[AES_KEY_SIZE] = {0x91, 0xf7, 0x16, 0x18, 0xe4, 0xe8, 0xcb, 0xf4, 0x97, 0x9f, 0x4e, 0x61, 0x3f, 0xcb, 0xfb, 0x50};

As it is a BLE application, the PSA Crypto Software Component is already installed in the project. You just need to import the crypto.h file.

#include "psa/crypto.h"

The psa_key_attributes_t object specifies the attributes for the new key during the creation process. The application must set the key type and size, key algorithm policy, and the appropriate key usage flags in the attributes for the key to be used in any cryptographic operations. If the key creation succeeds, the PSA Crypto will return an identifier for the newly created key.

  // Setup key attributes
  psa_key_attributes_t key_attr = psa_key_attributes_init();
  // The state object for multi-part cipher operations
  psa_cipher_operation_t cipher_op = psa_cipher_operation_init();

  // Import the key
  psa_set_key_type(&key_attr, PSA_KEY_TYPE_AES);
  psa_set_key_bits(&key_attr, 128);
  psa_set_key_usage_flags(&key_attr, PSA_KEY_USAGE_ENCRYPT);
  psa_set_key_algorithm(&key_attr, PSA_ALG_ECB_NO_PADDING);
  status = psa_import_key(&key_attr, key, key_len, &key_id);

Now you can encrypt sample data with the created key using the psa_cipher_encrypt_setup(), psa_cipher_update() and psa_cipher_finish() functions. In the application, the aes_ecb_encrypt_message() function encryptes the sample data and then the encrypted cipher is copied to the custom advertisement structure.

Build and flash the application and obtain the results with the smartphone.

1. Open the EFR Connect app.

2. Open the Bluetooth Browser.

3. Find the device advertising as "Lab 3" and click on it.

4. Check the Manufacturer Specific Data section

To verify the result of the encryption process, use an online tool.

Simplicity Studio 5 includes the PSA Crypto platform examples for key handling, symmetric and asymmetric cryptographic operations. See the corresponding readme.html file for details about each PSA Crypto platform example.