Skip to content

Latest commit

 

History

History
298 lines (215 loc) · 17.8 KB

configuring.rst

File metadata and controls

298 lines (215 loc) · 17.8 KB

Configuring Bluetooth Mesh in |NCS|

The Bluetooth® Mesh support is controlled by :kconfig:option:`CONFIG_BT_MESH`, which depends on the following configuration options:

When the Bluetooth LE Controller is located on a separate image (like on the :ref:`zephyr:nrf5340dk_nrf5340` and :ref:`zephyr:thingy53_nrf5340` boards), the following configuration must be applied to the Bluetooth LE Controller configuration:

Optional features configuration

Optional features in the Bluetooth Mesh stack must be explicitly enabled:

The persistent storage of the Bluetooth Mesh provisioning and configuration data is enabled by :kconfig:option:`CONFIG_BT_SETTINGS`. See the :ref:`zephyr:bluetooth-persistent-storage` section of :ref:`zephyr:bluetooth-arch` for details.

Mesh models

The |NCS| Bluetooth Mesh model implementations are optional features, and each model has individual Kconfig options that must be explicitly enabled. See :ref:`bt_mesh_models` for details.

Mesh settings/performance

The following configuration options are used to configure the behavior and performance of a Bluetooth Mesh network. For more information about configuration options affecting the memory footprint of Bluetooth Mesh, see :ref:`memory footprint optimization guide for Bluetooth Mesh <app_memory_bt_mesh>`.

Additional configuration options

This section lists additional configuration options that can be used to configure behavior and performance of Bluetooth Mesh. The provided values are meant as suggestions only, and should be individually adjusted for each application.

Logging

GATT Proxy performance

These options are only compatible with devices supporting Bluetooth Low Energy (LE) v4.2 or higher.

Bluetooth settings/performance

The following configuration options are used to configure the Bluetooth Low Energy behavior and performance:

Disabled and unused Bluetooth features

The following feature options are by default disabled in the samples, but it needs to be considered if any of them are required by the application and thus should be enabled:

Emergency data storage (EMDS)

The following configuration options should be considered in case of large networks with high demands on storing the replay protection list (RPL) data. This will require additional hardware. For more information, see :ref:`emds_readme`.

Low Power node (LPN)

The Low Power node (LPN) is a :ref:`power optimization <app_power_opt>` feature specific to Bluetooth Mesh.

The following configuration options are relevant when using the LPN feature:

Persistent storage

Zephyr's Mesh implementation has been designed to use the :ref:`settings <zephyr:settings_api>` subsystem to store internal states and options in the :ref:`persistent storage <zephyr:bluetooth_mesh_persistent_storage>`. The settings subsystem can be used with different backends. Bluetooth Mesh is configured with the :ref:`non-volatile storage (NVS) <zephyr:nvs_api>` as the settings backend.

Using the settings subsystem based on NVS can in some cases result in a significant store time increase. In a worst case scenario, the store time can be up to several minutes. This can for example happen when storing a large size replay protection list. It is recommended to configure the settings subsystem's internal caches to improve the performance.

NVS lookup cache reduces the number of search loops within NVS' application table.

The Settings NVS name cache reduces the number of search loops of internal parameter identifiers, keeping them in memory.

The size of the Settings NVS name cache, :kconfig:option:`CONFIG_SETTINGS_NVS_NAME_CACHE_SIZE`, is recommended to be at least equal to the number of settings entries the device is expected to store.

The Bluetooth Mesh stack stores the following data persistently:

The following data is stored for each model by the Bluetooth Mesh stack:

  • Model subscription state
  • Model publication state
  • Bound application key(s)
  • Subscription list for group addresses
  • Subscription list for virtual addresses
  • Label UUIDs the model is subscribed to
  • Model-specific data

Model data stored persistently can be found under the Persistent storage section of the corresponding model documentation.

Using the :ref:`bluetooth_mesh_sensor_server` sample as an example, configured according to the sample's :ref:`configuration guide <bluetooth_mesh_sensor_server_conf_models>`, results in the following list of possible entries (entries mentioned above are not included unless specifying the amount of entries):

  • 32 RPL entries - since the default Networked Lighting Control (NLC) configuration is used (:kconfig:option:`CONFIG_BT_MESH_NLC_PERF_DEFAULT` is set), the RPL size is 32.
  • Application keys - three keys are used.
  • Bound application keys - each of the three Sensor Server and Sensor Setup Server models has one bound application key.
  • Network keys - only one key is used.
  • Model subscriptions - each of the three Sensor Server and Sensor Setup Server models subscribes to a group address.
  • Model publication information - each of the three Sensor Server models publishes to a group address.
  • Virtual addressing is not used.
  • :ref:`Sensor Server model data <bt_mesh_sensor_srv_persistent_readme>` - each of the three Sensor Server models stores the following data:
    • Minimum interval
    • Delta thresholds
    • Fast period divisor
    • Fast cadence range
  • The following values are stored in the sample:
    • Temperature range
    • Presence motion threshold
    • Ambient light level gain

Adding up all entries, it is worth setting the cache size to minimum 71.

Security toolbox

Zephyr's Mesh security toolbox implementation uses third-party crypto library APIs (such as CMAC, AES-CCM, and HMAC-SHA-256) for implementing the encryption and authentication functionality.

The Bluetooth Mesh security toolbox based on the `PSA Certified Crypto API`_ does not operate with open key values. After Bluetooth Mesh receives an open key value, it immediately imports the key into the crypto library and receives the unique key identifier. The key identifiers are used in the security toolbox and stored in the persistent memory. The crypto library is responsible for storing of the key values in the Internal Trusted Storage (`PSA Certified Secure Storage API 1.0`_). Bluetooth Mesh data structures based on Tinycrypt and the PSA API, as well as images of these structures stored in the persistent memory, are not compatible due to different key representations. When a provisioned device updates its firmware binary from the Tinycrypt-based toolbox to firmware binary that uses the PSA API based toolbox, a provisioned device must be unprovisioned first and reprovisioned after the update. The provisioned device cannot restore data from the persistent memory after firmware update. If the image is changed over Mesh DFU, it is recommended to use :c:enumerator:`BT_MESH_DFU_EFFECT_UNPROV`.

A provisioned device can update its firmware image from the Tinycrypt-based toolbox to firmware image that uses the PSA API based toolbox without unprovisioning if the key importer functionality is used. The :kconfig:option:`CONFIG_BT_MESH_KEY_IMPORTER` Kconfig option enables the key importer functionality. The key importer is an application initialization functionality that is called with kernel initialization priority before starting main. This functionality reads out the persistently stored Bluetooth Mesh data and if it finds keys stored by the Tinycrypt-based security toolbox, it imports them over the PSA API into the crypto library and stores the key identifiers in a format based on the PSA API toolbox. Once the new firmware image starts Bluetooth Mesh initialization, the persistent area already has the stored data in the correct format.

The device can be vulnerable to attacks while the device uses the key importer functionality. The following two types of security risks are possible:

  • If the device is provided with a new image with the key importer functionality enabled, the new image is not yet activated and the attacker can write arbitrary data in the persistent memory during this time by whichever methods. The fake keys might be imported to the PSA crypto library after the next device reset (which activates the new firmware with the key importer). The device gets provisioned to the attackers network and the attacker can read out the mesh state data from the device.

    Mitigation:

    • Ensure that the device is protected from unauthorized writes to the non-volatile storage.

  • Even after the key importer imports the keys to the crypto library, the plain text values are left in the flash until the next garbage collection is triggered by the storage backend.

    Mitigation:

    • Ensure that the device is protected from unauthorized reads (such as reading flash from programmer, or using mcumgr shell commands) from the non-volatile storage.
    • Execute a key refresh procedure for all existing keys used on the entire network as soon as possible by excluding the compromised device, if any. The mechanism to determine if the device is compromised is up to the OEM developers.

Additionally, after upgrading the device firmware with the key importer functionality enabled, and once the key import is complete, it is recommend to update device firmware with the key importer functionality disabled as soon as possible.