Bluetooth Mesh Provisioning Security Best Practices#

Security of the provisioning process is a critical component of the overall Bluetooth mesh network security. The provisioning process is designed with this in mind and provides security features that, when used correctly, help defend the network against attacks targeting device provisioning.

This document provides a quick overview of the provisioning process security and describes best practices that can be used to hinder attackers.

For details of the provisioning security, refer to the Mesh Protocol specification, Section 5 overall and Sections 5.4.2 and 5.4.3 in particular.

Bluetooth SIG also offers an informational publication on Bluetooth Mesh Security Overview that provides recommendations on how to use the Mesh security toolbox in general, including provisioning.

Provisioning Process#

Mesh provisioning can be roughly divided into the following five phases:

  • Session establishment

  • Capability negotiation

  • Public key exchange

  • Device authentication

  • Provisioning data distribution

Session Establishment#

In session establishment, an unprovisioned device announces that it is ready to be provisioned by transmitting unprovisioned device beacons or service advertisements for mesh provisioning GATT service. Both of these contain the device UUID (a 128-bit identifier for the device) as well as an indication of what out-of-band technologies the device might support. The Provisioner establishes a provisioning session to the device when it observes the unprovisioned device's transmissions.

Capability Negotiation#

Once a provisioning session is established, the device declares its capabilities to the Provisioner. These capabilities include the following:

  • Which provisioning algorithms the device supports; currently, two provisioning algorithms are defined:

    • BTM_ECDH_P256_HMAC_SHA256_AES_CCM -- defined in Mesh Protocol specification v1.1

    • BTM_ECDH_P256_CMAC_AES128_AES_CCM -- defined in Mesh Profile specification v1.0

  • If the device supports an out-of-band EC public key or not

    • Devices supporting Certificate-based Provisioning will support an out-of-band EC public key

  • If the device supports input, output, or static out-of-band authentication data

  • Characteristics of output out-of-band authentication data, if supported

  • Characteristics of input out-of-band authentication data, if supported

The Provisioner decides, based on device capabilities, its own capabilities, and restrictions configured by the application, which provisioning algorithm it will use, whether out-of-band public key will be used, and whether out-of-band authentication data will be used. It then communicates its decision to the device to conclude capability negotiation.

For example, suppose that the unprovisioned device has a numeric keypad and the Provisioner has a display that can show alphanumeric sequences (such as a dot matrix display). The Provisioner can then decide to make use of these hardware features for out-of-band authentication during provisioning.

The Provisioner is free to not provision any device that does not meet the minimum requirements set by the network operator. For example, the network operator may consider it a mandatory requirement that devices support some form of an out-of-band EC public key, and the Provisioner can abort the provisioning session for devices that do not support it.

While the Provisioner has the final say in what provisioning features will be used, Mesh Protocol 1.1 allows a device to request that out-of-band authentication data is used; and if it is not possible, the Provisioner has to abort the provisioning instead of forcing no out-of-band authentication data on the device.

Public Key Exchange#

After capability negotiation, the Provisioner and the unprovisioned device exchange EC public keys, so that each is able to derive an EC Diffie-Hellman shared secret independently. The shared secret will be the basis of provisioning security, as important data such as session key will be derived from it.

The Provisioner will always generate a fresh ephemeral EC key for every provisioning attempt and deliver it to the unprovisioned device in-band over the provisioning session (that is, using the Bluetooth radio).

The unprovisioned device will do the same when an out-of-band public key is not used. If an out-of-band EC public key is used, then the Provisioner must acquire it using the out-of-band mechanism that gives access to the key before it can compute the shared secret.

For example, in Certificate-based Provisioning, the out-of-band mechanism can be an HTTPS request to a key server over the Internet. Using that, of course, requires that the Provisioner has IP connectivity and a TCP/IP stack implementation.

Device Authentication#

Once the public key exchange is complete, the Provisioner authenticates the device. The authentication is based on both the Provisioner and the unprovisioned device knowing the exact same out-of-band authentication data and using it in cryptographic computations in order to independently compute the same results. How the authentication data knowledge is shared depends on the chosen authentication method, as described below:

  • For input out-of-band authentication, the Provisioner chooses a random value as the authentication data and outputs it to the user. The user must input the same value to the unprovisioned device.

  • For output out-of-band authentication, the unprovisioned device chooses a random value as the authentication value and outputs it to the user. The user must input the same value to the Provisioner.

  • For static out-of-band authentication, the authentication data may be chosen randomly by the unprovisioned device, or it may be pre-programmed to the device at the factory. The Provisioner will read the value using an out-of-band technology, such as a QR code or an NFC tag.

  • If none of the above is used, the authentication data is essentially zero.

The specification requires that authentication data for output out-of-band and input out-of-band authentication must be freshly generated for each attempt, not reused across multiple attempts.

The specification also requires that authentication data used for Mesh provisioning must not be used in Bluetooth LE pairing, and vice versa. Distinct data must be used for each. When pre-programmed static out-of-band authentication is used, this means that the device must be pre-programmed with two values, one for provisioning and one for pairing.

Provisioning Data Distribution#

Once the device authentication completes, both devices will independently create a session encryption key from the shared secret and other input material. The Provisioner will use the session encryption key to encrypt the provisioning data to send to the unprovisioned device. Once the unprovisioned device receives and decrypts the provisioning data, it can make use of it to gain access to the network.

After provisioning data is distributed, the provisioning session will be torn down and the provisioning process completes.

Provisioning Best Practices#

Consider Device UUID Filtering#

Depending on the use case, the Provisioner might know what devices it is supposed to provision. For example, a shipping manifest for a deployment could include device UUIDs of the devices to be set up.

If the information is available, Provisioner should not provision any device with a UUID that is not on the expected devices list.

Furthermore, the Provisioner should know what devices have already been provisioned and recognize their device UUIDs; it should not reprovision those devices again unless it is known the devices have been factory reset intentionally.

Use the Latest Provisioning Algorithm#

Preferably, use the newer algorithm, BTM_ECDH_P256_HMAC_SHA256_AES_CCM, and only use the older algorithm as a fallback if provisioning a legacy device that does not implement the newer one.

It is highly recommended that fallback to the older algorithm is only done if it is positively known that legacy devices need to be provisioned. Fallback should not be done if it is known that devices being provisioned support Mesh Protocol specification v1.1.

Consider Using Out-of-Band Public Key#

The EC public key exchange and the ECDH shared secret derivation helps to protect provisioning against passive eavesdropping even when both EC public keys are exchanged in-band. It will, however, not protect against an active man-in-the-middle attack.

If there is a chance of an active man-in-the-middle attack, device public key out-of-band delivery helps to protect against such attacks over Bluetooth.

Note that the out-of-band technology used to access the device public key must also be resilient to attacks to provide any benefit.

Note that if the Provisioner decides to use an out-of-band EC public key and it fails to access the key due to an out-of-band mechanism error (e.g., the certificate server is not reachable) the Provisioner must then abort the provisioning session instead of silently falling back to using in-band keys.

Consider PKI Integrity#

When using Certificate-based Provisioning, the security of the data embedded in device certificates depends on the integrity of the PKI used to produce the certificate.

The network operator is responsible for choosing the root certificates on which the certificate validation during provisioning builds. Only trustworthy root certificates should be included in the set of root certificates the Provisioner uses for certificate validation. Documents such as the Certificate Authorities' certificate policies and Certification Practice Statements can help in making PKI decisions.

Certificate Authorities may issue certificates with clearly declared certificate policies (policy identifiers recorded as certificate extensions). A Provisioner may have a list of acceptable policies in addition to having a set of trusted root certificates.

Consider Using Out-of-Band Authentication Data#

As with out-of-band public key, if there is a chance of an active man-in-the-middle attack, using out-of-band authentication data will help to protect against such attacks over Bluetooth.

Note that the out-of-band technology used to access the authentication data must also be resilient to attacks to provide any benefit.

It is important to note that, if out-of-band authentication data is used, the recommended BTM_ECDH_P256_HMAC_SHA256_AES_CCM provisioning algorithm must be used as well. This is because the older provisioning algorithm has security flaws that affect authentication.

It is very important to provide a sufficient amount of entropy in the authentication data to the provisioning procedure

If input or output out-of-band authentication is used, it is important to note that the specification unfortunately allows input and output actions (ways to provide the data) that provide only a very limited amount of entropy. This can make the authentication susceptible to brute-forcing or even simply guessing.

Blink, Beep, and Vibrate output out-of-band actions are not recommended to be used at all due to the extremely low entropy that they provide.

Push and Twist input out-of-band actions are not recommended to be used at all for the same reason.

Output Numeric and Input Numeric actions are not recommended to be used as they also provide a relatively low entropy. Note the following:

  • When Output Numeric or Input Numeric is used, the authentication data is constructed from a string of decimal digits, and the number of possible permutations is 10 to the power of N, where N is the number of digits. This means that, for example, 8 digits provides only 26 bits of entropy to the authentication whereas 6 digits provides only 19 bits of entropy.

Output Alphanumeric and Input Alphanumeric actions can be used, but note the following:

  • When Output Alphanumeric or Input Alphanumeric is used, the data is constructed from a string of decimal digits and uppercase English letters, and the number of possible permutations is 36 to the power of N, where N is the number of digits and letters. For example, 8 numbers and letters provides 41 bits of entropy to the authentication whereas 6 numbers and letters provides only 31 bits of entropy.

When static out-of-band authentication is used, 256 bits of entropy can be provided to the authentication. It is highly recommended that the full length of the authentication data is made use of when static out-of-band authentication data is generated. It is not recommended to use a shorter length and pad the remainder with zeroes, but at minimum more than 128 bits of entropy should be used.

No out-of-band authentication and no out-of-band public key exchange can broadly be compared to Bluetooth LE Secure Connections pairing with Just Works association model; it is convenient to the user, and secure enough if there is no active man-in-the-middle attacker present.