AN1386: Bluetooth Mesh Certificate-Based Provisioning

AN1386: Bluetooth Mesh Certificate-Based

Provisioning

Certificate-Based Provisioning (CBP) is defined in Bluetooth

Mesh protocol specification version 1.1. CBP ensures that de-

vices joining a Bluetooth Mesh network are authentic. This au-

thentication method mitigates the risk of rogue devices joining

the network by spoofing the identity of authentic devices.

This application note describes how certificates are used to establish the authenticity

of devices wishing to join a mesh network.

KEY POINTS

• Certificate-based provisioning

• Bluetooth Mesh protocol specification

1.1

AN1386: Bluetooth Mesh Certificate-Based Provisioning

Introduction

silabs.com | Building a more connected world. Rev. 0.1 | 2

1 Introduction

Certificate-Based Provisioning makes mesh networks more secure by establishing an identity using a signed certificate chain. This can

prevent the possibility of rogue devices joining the network by spoofing the advertisement of a legitimate device. Certificate-Based Pro-

visioning mitigates this by requiring the device to present a signed certificate or chain of certificates which can be verified using standard

public key cryptography.

1.1 Requirements

Certificate-Based Provisioning is supported by the following devices:

Table 1.1. Supported Devices and Level of Support

Device

Support

EFR32xG21B

EFR32xG24B

Secure Vault

AN1386: Bluetooth Mesh Certificate-Based Provisioning

Theoretical Background

silabs.com | Building a more connected world. Rev. 0.1 | 3

2 Theoretical Background

2.1 Certificates

A digital certificate is simply a small, verifiable data file that contains identity credentials and a public key. That data is then signed either

with the corresponding private signing key, or a certificate authority’s private signing key. The digital certificate can be used to prove the

ownership of a public key.

• If it is signed using the corresponding private key, it is called a self-signed certificate.

• If it is signed by another private key, the owner of that private key is acting as a Certificate Authority (CA).

• A Certificate Authority (CA) is a trusted third party by both the owner and party relying on the certificate.

Concatenation of digital certificates builds a chain of trust.

• At the root of the chain is a self-signed certificate called a root certificate or a CA certificate.

• The root or CA certificate can be used to sign another certificate.

Figure 2.1. Digital Certificates and Chain of Trust

The private key is never included as part of the certificate. It must be stored separately and kept private. The security of the scheme relies

on protecting the private keys.

2.1.1 Key Usage

Version 3 of the X.509 standard provides the ability to restrict the purposes that a certificate’s public key can be used for. Bluetooth Mesh

CBP certificates must allow the ‘Key Agreement’ usage for the public key. This allows a shared secret to be established between the

provisioner and provisionee.

To learn more about certificates, see AN1268: Authenticating Silicon Labs Devices Using Device Certificates, which addresses certificates

in detail.

2.2 Bluetooth Mesh Certificate-Based Provisioning

Bluetooth Mesh Provisioning is described in the Bluetooth Mesh 1.1 Protocol specification. Refer to this document for specifics of provi-

sioning messages and certificate requirements. A certificate chain is used as the out-of-band (OOB) data for provisioning. Provisioning

related information is stored on a device as provisioning records. The device certificate can either be requested from the device during

provisioning or obtained by the provisioner from a URI indicated in the provisioning record. The provisioner requests the device certificate

by sending a Provisioning Record Request message with the ID set to ‘Device Certificate’ to the device to be provisioned. The provisionee

responds with a Provisioning Record Response message which includes a device certificate. If intermediate certificate(s) are present,

they will be requested by the provisioner and sent one at time. Up to fifteen (15) intermediate certificates can be used in the certificate

AN1386: Bluetooth Mesh Certificate-Based Provisioning

Theoretical Background

silabs.com | Building a more connected world. Rev. 0.1 | 4

chain. The provisioner verifies the certificate chain before proceeding with the provisioning process. In case the certificate chain cannot

be verified, the provisioning process is terminated.

2.2.1 Obtaining Device Certificates from URI

Device certificates and intermediate certificates may be retrieved by the provisioner from the internet using HTTPS protocol. The base

uniform resource indicator (URI) of the device certificate can be included provisioning record.

2.2.2 Requirements for Provisioners and Devices

The provisioner of the network must store the root-of-trust certificate for each chain of trust. The root certificate must not be sent from

device to provisioner during the provisioning process nor be able available for retrieval from the URI. It is the responsibility of the provi-

sioner to ensure the integrity of the root-of-trust certificate.

2.2.3 Verifying the Device Certificate

The provisioner must verify the authenticity of the device certificate received. In addition to verifying the authenticity of the certificate, as

defined in RFC5280, the Bluetooth Mesh protocol specification requires that the following criteria must be met:

• The device certificate must be verifiable, directly, or indirectly, by the root CA

• The device certificate is not expired

• The device certificate has not been revoked by any certificate revocation list (CRL)

The following table summarizes the fields of the device certificate which shall be present:

Table 2.1 Required Certificate Fields

Certificate Field Requirements

tbsCertificate As defined by RFC5280 with additional requirements as defined in this table

signatureAlgorithm Set to “ecdsa-with-SHA256”

SignatureValue signature computed as in RFC5280

Version “2”

serialNumber Must meet the requirements detailed in RFC5280

issuer Identifies the signer of the certificate. See RFC5280.

validity

• notBefore time should not be earlier than the manufacture date of the device

• notAfter time shall be set by the manufacturer

subject

Shall contain a valid distinguished name (DN) with the following restrictions:

• organization name of the DN shall be set to the vendor name

• common name of the DN shall contain the device UUID in

subjectPublicKeyInfo

As defined by RFC5280 with the following constraints:

• algorithm field shall contain “id-ecPublicKey” as the algorithm and secp256r1 curve as the pa-

rameters. See RFC5480 for details.

• subjectPublicKey field shall contain the public OOB key of the device

basicConstraints Extension

• cA field shall be present and set to FALSE

• pathLenConstraint shall not be present

keyUsage Extension keyAgreement bit shall be set as defined in RFC5280

AN1386: Bluetooth Mesh Certificate-Based Provisioning

Theoretical Background

silabs.com | Building a more connected world. Rev. 0.1 | 5

The following table summarizes the optional fields in the device certificate which may be included. These fields shall be used as defined

in RFC5280 without additional constraints.

Table 2.2 Optional Certificate Fields

Optional Certificate Fields

Authority key identifier

Subject key identifier

Certificate policies extension

Issuer Alternative Name

Subject Directory Attribute extension

CRL distribution points extension

Freshest CRL extension

Authority Information Access extension

Subject Information Access extension

All other fields defined by RFC5280 shall not be present in the device certificate.

AN1386: Bluetooth Mesh Certificate-Based Provisioning

Creating Example Certificate Authority and Device Certificate

silabs.com | Building a more connected world. Rev. 0.1 | 6

3 Creating Example Certificate Authority and Device Certificate

This section describes how to create an example certificate authority and device certificate. The method described here is only in-

tended for evaluation and should not be used in a production environment. For production, users are encouraged to obtain root

certificates from a qualified certificate authority (CA). Users are strongly discouraged from acting as their own CA.

Certificate-Based Provisioning, as its name suggests, relies on certificates. Each device that participates in Certificate-Based provisioning

must be preprogrammed with a:

• private key, which can be used to prove the identity of the device.

Note: It is critical that the device private signing key be stored securely.

• One of the following:

• Corresponding device certificate, which holds the identity of the device (including the public key of the device), optionally

with one or more intermediate certificates

• URI pointing to a server where the device certificate can be downloaded

Additionally, the provisioner must know which are the trusted devices. Therefore, the provisioner must be preprogrammed with the root

certificate(s) used to create the certificate chain of any device to be provisioned with a Certificate Authority (CA) Certificate, which can

be used to validate any certificate that belongs to a trusted device.

Putting this into practice, the following steps must be done before Certificate-Based Provisioning can be applied:

1. A CA Certificate must be created (with self-signing) along with a CA private key that will be used to sign all the device certificates.

This is done on a computer. Note that the private key must be securely stored, preferably in a hardware security module (HSM). At

a minimum, the private key must not leave this machine.

2. Each device must generate a private key. These private keys must be generated on the devices, and they must not leave the devices.

3. Each device must generate its device certificate signing request, which holds its public key (generated from its private key) and the

credentials.

4. Each device must get its device certificate signing request signed by the CA. To do this, the certificate signing request must be

transmitted to the central machine (this can be done via UART), and the signed certificate must be transmitted back to the device.

5. The CA certificate must be stored on the provisioner so that it can validate the device certificates of the provisionee devices.

Because this process is not easy to implement, Silicon Labs provides sample applications that do all the required steps.

• The Bluetooth Mesh - SoC CSR Generator sample app generates the private key and the device certificate signing request on the

device. It can also be used to connect to the certificate authority and send over the device certificate signing request to be signed.

• The create_authority_certificate.py (CA) Python script can be used to generate the CA certificate along with the private key. It also

creates a header file with the CA certificate that can be stored on the devices.

• The production_line_tool.py (PLT) Python script can be used for reading out the device certificate signing requests (CSRs) from

the requesting devices, signing the CSRs with the CA private key, and flashing them back to the device.

Note: the private key used by this script is visible in plain text, therefore this tool is not to be used in a secure production environment,

a hardware security module (HSM) must be used instead.

The Python scripts can be found in the following folder: {SDK_folder}/app/bluetooth/script/certificate_authorities.

AN1386: Bluetooth Mesh Certificate-Based Provisioning

Creating Example Certificate Authority and Device Certificate

silabs.com | Building a more connected world. Rev. 0.1 | 7

Figure 3.1. Signing the Device Certificates

To generate the device certificate and get it signed, follow this process:

1. Factory-reset your device to make sure that no keys and certificates are stored on it. You can do this with Simplicity Commander

using the Recover Bricked Device option in the GUI or with the following CLI command:

commander device recover.

2. Flash an Internal Storage Bootloader to your device. (Must be generated and built as a separate project.) See UG489, Gecko

Bootloader User Guide for specific instructions.

3. Create a new Bluetooth Mesh- SoC CSR Generator project in Simplicity Studio.

4. Open the slcp file of the project.

5. On the Overview tab, under Project Details, open the three-dots-menu, and click the Configuration button as shown below.

6. Modify the Certification Subject Data fields so that your certificate subject contains your company’s information.

7. Build and flash the project to your device. This will automatically generate the private-public key pair and the certificate signing

request on startup.

8. Create a CA certificate. Skip this step if you already have a root certificate you wish to use. Install the Python modules cryptography

and jinja2 as follows:

pip3 install cryptography

AN1386: Bluetooth Mesh Certificate-Based Provisioning

Creating Example Certificate Authority and Device Certificate

silabs.com | Building a more connected world. Rev. 0.1 | 8

pip3 install jinja2

Once these modules have been installed, create the CA certificate with the following command:

python3 {SDK_folder}\app\bluetooth\script\certificate authorities\create_author-

ity_certificate.py

Note: This certificate will be created with factory default parameters to customize the certificate with your own unique identifiers. See

the help menu for this script, which is available by running the following command:

python3 <Gecko sdk root>\app\bluetooth\script\certificate authorities\create_author-

ity_certificate.py -h.

9. The CA certificate can now be found in {SDK_folder}\app\bluetooth\script\certificate authorities\central_authority\certificate.pem.

10. Check the Jlink serial number of your debug adapter either with Simplicity Studio or with Simplicity Commander by using the com-

mand

commander adapter probe.

11. Run the

production_line_tool.py python script on your computer with the following parameters:

Python3 {SDK_folder}\app\bluetooth\script\certificate authorities\produc-

tion_line_tool.py --serial <serialnumber>

This will read out the signing request, sign the device certificate, and flash the signed certificate on the device. Note: the 'serial'

parameter is not required if only one device is connected to your PC.

12. Now the key pair and the signed certificate are stored on your device. You can flash a new application to the device. At this stage, it

is important to ensure that the flash is not completely erased. Simply flashing a new application, and bootloader if required, are

sufficient.

Note: It is important to add a bootloader to your new project that has secure boot enabled. This ensures that the firmware you programmed

to the device cannot be changed. See AN1218: Secure Boot with RTSL

for more information on secure boot.

AN1386: Bluetooth Mesh Certificate-Based Provisioning

Preparing a Device for Certificate-Based Provisioning

silabs.com | Building a more connected world. Rev. 0.1 | 9

4 Preparing a Device for Certificate-Based Provisioning

4.1 Device

Once a device certificate, and optionally any intermediate certificates, have been installed on the device, there are a few steps as follows

to configure the device for Certificate-Based Provisioning:

1. Call

sl_btmesh_node_init_oob() to indicate that the device has an out-of-band public key.

2. Enable support for provisioning records by calling sl_btmesh_node_init_provisioning_records().

3. Start unprovisioned beaconing by calling

sl_btmesh_node_start_unprov_beaconing().

AN1386: Bluetooth Mesh Certificate-Based Provisioning

Example

silabs.com | Building a more connected world. Rev. 0.1 | 10

5 Example

5.1 BTMesh SOC Empty CBP

This section covers the use of the “Bluetooth Mesh – SoC Empty with Certificate-Based Provisioning Support” sample application found

in the Gecko SDK.

5.1.1 Creating Device Certificate on Device

1. Follow the steps for creating a device certificate, which are detailed in section 3 Creating Example Certificate Authority and Device

Certificate.

2. Create an instance of the “Bluetooth Mesh – SoC Empty with Certificate-Based Provisioning Support” sample application for your

chosen device.

3. Build the application and flash the output file to your device.

5.2 Provisioning with the Bluetooth Mesh mobile app

Silicon Labs Bluetooth Mesh mobile app supports Certificate-Based Provisioning starting in version 4.1.0. To being provisioning a node

with CBP, open the Bluetooth Mesh mobile app, select the Provision tab, and tap the scan icon as shown below.

AN1386: Bluetooth Mesh Certificate-Based Provisioning

Example

silabs.com | Building a more connected world. Rev. 0.1 | 11

In the dialog for the unprovisioned node, ensure that the Use Certificate-based Provisioning option is enabled then tap the Obtain

certificate from the device icon as shown below.

AN1386: Bluetooth Mesh Certificate-Based Provisioning

Example

silabs.com | Building a more connected world. Rev. 0.1 | 12

Once the device certificate has been sent, the Device certificate status changes to Available as shown below.

Tap the Select certificate icon to browse for the root certificate. Note: The root certificate must be accessible to the mobile device either

through its filesystem or in a cloud storage service such as Dropbox. Once the root certificate file has been selected, it is shown on the

Provisioning Records Summary dialog.

Tap the Provisioning button at the bottom of the screen to complete the provisioning process.

5.3 Provisioning with the BT Mesh Host Provisioner Sample Application

The btmesh-host_provisioner sample application runs on a posix-type platform such as RaspberryPi. For instructions on getting started

building the Host Provisioner sample app, see section 2.3 of AN1371 - Bluetooth Mesh NCP Host Provisioner Example Walkthrough

Note that when exporting the Bluetooth Mesh Host Provisioner code it is necessary to include the CBP flag as follows:

make export CBP=1

To enable Certificate-Based Provisioning, rebuild the sample with the following command:

make CBP=1

5.3.1 Installing Root Certificates

For the BT Mesh provisioner to validate device certificate chains, it must have the root certificate for those chains. The root certificates

must be stored in PEM format in the file CA/ca-certificate.crt under the BT Mesh host provisioner source folder.

Example:

AN1386: Bluetooth Mesh Certificate-Based Provisioning

Example

silabs.com | Building a more connected world. Rev. 0.1 | 13

The root certificate generated by the script mentioned in section will be C:\Users\<user>\SimplicityStudio\SDKs\gecko_sdk\app\blue-

tooth\script\certificate_authorities\central_authority\certificate.pem.

Copy this file to the provisioner host:

<path to exported files>/app/btmesh/example_host/btmesh_host_provisioner/CA/ca-certificate.crt

5.3.2 Specifying a Base URI for Certificate Retrieval

This section describes how to customize the sample application to include a base URI for certificate retrieval in the provisioning records.

1. Add the following code to the top level of the project’s app.c file.

2. Edit the ‘base_uri’ member to point to the desired URI.

3. Add the following line to app_init():

struct mesh_const_provisioning_record {

const uint8_t *ptr; //< Provisioning record data

uint16_t len; //< Length of provisioning record data

};

/** Number of spec-defined intermediate certificates */

#define MESH_INTERMEDIATE_CERTIFICATE_COUNT 15

struct mesh_const_provisioning_records {

/** Certificate-based provisioning base URI */

struct mesh_const_provisioning_record base_uri;

/** Complete local name */

struct mesh_const_provisioning_record complete_local_name;

/** Appearance */

struct mesh_const_provisioning_record appearance;

/** Intermediate certificate 1 to 15 */

struct mesh_const_provisioning_record intermediate_certificate[MESH_INTERMEDIATE_CERTIFI-

CATE_COUNT];

};

extern const struct mesh_const_provisioning_records *mesh_const_provisioning_records;

static const struct mesh_const_provisioning_records records = {

.base_uri = {

(const uint8_t *)"\x17//www.example.com/",

19,

.complete_local_name = {

NULL,

.appearance = {

NULL,

.intermediate_certificate = {

{ NULL, 0 }, { NULL, 0 }, { NULL, 0 }, { NULL, 0 }, { NULL, 0 },

};

AN1386: Bluetooth Mesh Certificate-Based Provisioning

Example

silabs.com | Building a more connected world. Rev. 0.1 | 14

4. Build the project and download the binary to the target board.

5. Scan for the node as described in section 5.2 above. Now the BTMESH mobile app will show that the URI is available as shown

below:

5.3.3 Running the BT Mesh Host Provisioner

The BT Mesh host provisioner can provision nodes to a network with the node’s 128-bit UUID which is obtained by scanning as shown

below:

./exe/btmesh_host_provisioner -u <serial port> --scan --c

mesh_const_provisioning_records = &records;

AN1386: Bluetooth Mesh Certificate-Based Provisioning

Example

silabs.com | Building a more connected world. Rev. 0.1 | 15

as desc

Once the node’s UUID has been found, it can be used to provision the device as shown below:

./exe/btmesh_host_provisioner -u <serial port. –c –provision <UUID>

Example:

./exe/btmesh_host_provisioner -u /dev/ttyACM0 --c -b 115200 --provision

9c93e21b4ea4a65d871031d7f67bb702

Now the node is provisioned on the network and can be configured for groups and functionality. For specifics, refer to AN1371, B

luetooth

Mesh NCP Host Provisioner Example Walkthrough.

Silicon Laboratories Inc.

400 West Cesar Chavez

Austin, TX 78701

USA

www.silabs.com

IoT Portfolio

www.silabs.com/IoT

SW/HW

www.silabs.com/simplicity

Quality

www.silabs.com/quality

Support & Community

www.silabs.com/community

Simplicity Studio

One-click access to MCU and wireless

tools, documentation, software,

source code libraries & more. Available

for Windows, Mac and Linux!

Disclaimer

Silicon Labs intends to provide customers with the latest, accurate, and in-depth documentation of all peripherals and modules available for system and software imple-

menters using or intending to use the Silicon Labs products. Characterization data, available modules and peripherals, memory sizes and memory addresses refer to each

specic device, and “Typical” parameters provided can and do vary in dierent applications. Application examples described herein are for illustrative purposes only. Silicon

Labs reserves the right to make changes without further notice to the product information, specications, and descriptions herein, and does not give warranties as to the

accuracy or completeness of the included information. Without prior notication, Silicon Labs may update product rmware during the manufacturing process for security or

reliability reasons. Such changes will not alter the specications or the per formance of the product. Silicon Labs shall have no liability for the consequences of use of the infor-

mation supplied in this document. This document does not imply or expressly grant any license to design or fabricate any integrated circuits. The products are not designed or

authorized to be used within any FDA Class III devices, applications for which FDA premarket approval is required or Life Support Systems without the specic written consent

of Silicon Labs. A “Life Support System” is any product or system intended to support or sustain life and/or health, which, if it fails, can be reasonably expected to result in

signicant personal injury or death. Silicon Labs products are not designed or authorized for military applications. Silicon Labs products shall under no circumstances be used

in weapons of mass destruction including (but not limited to) nuclear, biological or chemical weapons, or missiles capable of delivering such weapons. Silicon Labs disclaims

all express and implied warranties and shall not be responsible or liable for any injuries or damages related to use of a Silicon Labs product in such unauthorized applications.

Note: This content may contain o ensive terminolog y that is now obsolete. Silicon Labs is replacing these terms with inclusive language wherever possible. For more

information, visit www.silabs.com/about-us/inclusive-lexicon-project

Trademark Information

Silicon Laboratories Inc.

, Silicon Laboratories

, Silicon Labs

, SiLabs

and the Silicon Labs logo

, Bluegiga

, Bluegiga Logo

, EFM

, EFM32

, EFR, Ember

, Energy Micro, Energy

Micro logo and combinations thereof, “the world’s most energy friendly microcontrollers”, Redpine Signals

, WiSeConnect , n-Link, ThreadArch

, EZLink

, EZRadio

, EZRadioPRO

Gecko

, Gecko OS, Gecko OS Studio, Precision32

, Simplicity Studio

, Telegesis, the Telegesis Logo

, USBXpress

, Zentri, the Zentri logo and Zentri DMS, Z-Wave

, and others

are trademarks or registered trademarks of Silicon Labs. ARM, CORTEX, Cortex-M3 and THUMB are trademarks or registered trademarks of ARM Holdings. Keil is a registered

trademark of ARM Limited. Wi-Fi is a registered trademark of the Wi-Fi Alliance. All other products or brand names mentioned herein are trademarks of their respective holders.