Bluetooth Mesh Message Decoder Library#

Introduction#

This library provides utilities for decrypting, authenticating, and decoding Bluetooth Mesh messages. It relies on the PSA Crypto API for cryptographic functionality.

The library supports the following Mesh stack features:

• Decrypting and authenticating Mesh Network PDUs with

  • Flooding credentials

  • Directed forwarding credentials

  • Friendship credentials (provided that friendship establishment is observed)

• Decoding decrypted Mesh Network PDU contents

• Decoding Lower Transport PDU contents

• Reassembling segmented Upper Transport messages

  • Provided that all segments are observed

• Decoding Transport Control messages

• Decrypting and authenticating Access messages

• Authenticating Mesh beacons

• Decoding Mesh beacons

The library does not support the following Mesh stack features:

• Network cache

  • It is up to the application to process or not process data that is decoded from receives messages when it can be retransmitted

• Replay protection

  • It is up to the application to process or not process data that is decoded from receives messages when it can be replayed

• Scanning for Mesh traffic

  • It is the application's responsibility to supply scanned data to the library

• Decoding model messages

  • This is up to the application or a higher layer library

• GATT traffic

  • Potentially to be added later

• The provisioning protocol

  • Potentially to be added later

Quickstart#

When building an application the library needs to be configured accordingly by

• Setting the optional feature support;

• Setting the number of encryption keys to support;

• Setting the number of label UUIDs to support;

• Setting the number of SAR reassemblies to support;

• Setting the number of friendships to track;

These can be done by editing sl_mesh_decoder_config.h

Furthermore, it needs to be ensured that PSA Crypto is compiled with enough resources to manage all necessary encryption keys including all derivations for the network key (seven if directed forwarding credentials are supported) and friendship derivations (two per friendship).

An application using the library should do the following:

• Initialize a decoder context: sl_mesh_decoder_create()

• Install an initial set of encryption keys:

  • sl_mesh_decoder_add_network_key() – note that this will generate multiple derived keys internally

  • sl_mesh_decoder_add_application_key()

  • sl_mesh_decoder_add_device_key()

• Install a set of label UUIDs (if any) by sl_mesh_decoder_add_virtual_label_uuid()

• Know the current IV index for the network

• Feed incoming network PDU data to sl_mesh_decoder_decrypt_net_pdu()

• If decryption succeeds:

  • Examine the network PDU contents, starting with sl_mesh_net_pdu_is_valid()

  • Examine the lower transport PDU within network PDU payload, starting with sl_mesh_net_pdu_contains_valid_trans_pdu()

  • Make use of the SAR reassembler for segmented messages (sl_mesh_reassembler_add_segment())

  • Examine transport control message contents, starting with sl_mesh_pointer_contains_valid_control_message()

    • Make use of friendship tracking (sl_mesh_friendship_add_friend_request(), sl_mesh_friendship_add_friend_offer())

  • Feed access message data to sl_mesh_decoder_decrypt_access_pdu()

  • If decryption succeeds:

    • Examine access message contents, starting with sl_mesh_access_pdu_contains_valid_access_message()