Mesh Security

You are here: Configuration > Mesh Security 2

Mesh Security Set in Target

Note: The Bluetooth SIG is currently in the process of developing specifications for use of Bluetooth technology with mesh networking. Any reference to "Smart Mesh" contained herein is only in the context of Frontline software and does not represent SIG approved terminology.

Decryption of Bluetooth low energy using mesh networking requires a key key setskey or key sets. This information must be manually entered into the MeshOptions.ini file located in the system My Decoders folder. Refer to Changing Default File Locations for information on folder locations.

Open a text editor program, such as Windows Notepad, and make the following changes to the MeshOptions.ini file.

For Bluetooth technology using mesh networking,

*Bluetooth* technology using mesh networking Keys Format
Name	Enter as	Description
Technology Identifier	[mesh]	Identifies the beginning of a set of mesh keys.
Friendly Name		string, 2 word maximum.
IV Index		8 bytes, hexadecimal
Application Key		16 bytes, hexadecimal
Network Key		16 bytes, hexadecimal
Device Key (Optional)		16 bytes, hexadecimal

Note: The Application Key will be substituted for the Device Key when the AFK bit is not set and the Device Key is absent in the MeshOptions.ini file. AKF is the Application Key Flag and is a single bit.

Enter the fields in the order shown and separated by commas. The following code is an example of Bluetooth technology using mesh networking decryption key entry. Three mesh keys shown. Note that "Sample5" and "Sample6" keys do not use the optional Device Key.

[mesh]

// Key Format - FriendlyName, IV-Index, App Key, Net Key, Dev Key (Optional)

Sample1, 00000002, 63964771734fbd76e3b40519d1d94a48, 7dd7364cd842ad18c17c2b820c84c3d6, 63964771734fbd76e3b40519d1d9

Sample5, 01020304, f1a24abea9b86cd33380a24c4dfbe743, efb2255e6422d330088e09bb015ed707

Sample6, 01020304, f1a24abea9b86cd33380a24c4dfbe744, efb2255e6422d330088e09bb015ed708

The Friendly Name is displayed in the summary column of the Mesh tab in the Frame Display. This will help the user to filter based on the Friendly Name.

Note: "Unknown Network" will be displayed when the given key set(s) defined in MeshOptions.ini is unable to decrypt a certain frame.

For CSRmesh,

CSRmesh Key Set Format
Name	Enter as	Description
Technology Identifier Tag	[CSRmesh]	Required to differentiate from [mesh]. Software will only look for keys after this tag, ignoring comments. Case insensitive within the brackets.
Key set	Name, passphrase	Comma separated: Name = the network name. passphrase = the network key. If not present a key is not necessary.

The following code is an example of CSRmesh decryption key set entry.

[csrmesh]

// Format: My Network, My Password //My Comments

MySampleHome, Password

test

Test Home 1, test1

TestHome2, test2

BT, bluetooth

BT1, bluetooth1

BT2, bluetooth2

Frame Display File Menu

Loading keyskey setskeys or key sets

When the Frontline software is initially loaded, keys key setskeys or the key sets will be automatically read from the MeshOptions.ini file. If the keyskey setskeys or the key sets are modified while the Frontline software is running, decoders must be reloaded and the companion files must be recreated for the change to take effect. Follow these steps to reload the decoders.

In the Frame Display, click on the Reload Decoders icon , or select Reload Decoders from the File menu.
From the File menu, select Recreate Companion Files.

CSRmesh over GATT

ATT maintains a database which maps handles & UUIDs. When there is a connection request the mappings will be loaded to the initiator and/or advertiser sides of the database.

Phones can bypass pairing process for pre-paired devices. In this case, handle/UUID can be mapped by brute force using ATT_Handle_UUID_PreLoad.ini file. This file is to be placed in the root of My Decoders Folder.

For additional information refer to Bluetooth low energy ATT Decoder Handle Mapping.

Mesh in the Frame Display

In the Frame Display Summary pane, Mesh tabs appear for MTP, MASP, and MCP. The CSRMesh MTP tab displays the MASP and MCP protocols in the Summary pane.

CSRMesh MTP tab Summay pane display

The bearer can be "ATT" or "LE", and the protocols detected can be "MASP", "MCP", or "Unknown". When the MTP tab displays "Unknown" in the Protocol column it means

that the Generated MAC does not match the Received MAC in the packet,
that there is not a key set to decrypt the payload.

The CSRMesh MASP tab is shown in "CSRMesh MSRP tab with Decoder pane inset" shows the Decoder pane (inset) with the "Network Info" passphrase and network key shown but there is no network name.

CSRMesh MSRP tab with Decoder pane inset

The CSRMesh MCP tab is shown in "CSRMesh MCP tab with Decoder pane inset" shows the Decoder pane (inset) with the "Network Info" passphrase and network key and network name shown. The network name appears in the Network column of the Summary pane.

CSRMesh MCP tab with Decoder pane inset

Troubleshooting Tips

MeshOptions.ini Errors

Errors Associated with MeshOptions.ini
Error Displayed	Descripton
Error: IV Index should be 8 bytes	The IV Index read from MeshOptions.ini is not 8 bytes.
Error: App Key should be 16 bytes	The App Key read from MeshOptions.ini is not 16 bytes
Error: Net Key should be 16 bytes	The Net Key read from MeshOptions.ini is not 16 bytes
Error: Bad Format. Expected (Name, IVI, App, Net, Dev)	Something is wrong with formatting (Can be missing Friendly Name or missing IV Index, missing App Key,r missing Net key, or missing commas ‘,’).
Error: MeshOptions.ini file not found	The file cannot be located

CSRmesh Errors

Incorrect key set
- When the key set entered in MeshOptions.ini is incorrect, most of the Mesh Transport Protocol frames will contain Mesh Protocol Detected: Error.
- The term “Most” is used because it excludes Mesh Association Protocol (MASP) packets. MASP packets use a constant Passphrase of 0x00 || MASP.
  CSRmesh Bad MAC
- An error message will also be displayed, saying “MAC doesn’t match MASP or MCP”.
  This error simply means that the generated MAC does not match the received MAC. This error will also be generated in the case of a bad packet
Decryption Error
- The error message associated with a decryption error will say "Decryption Error".
Payload Size
- MTL payload<=9 bytes (MAC+TTL)
  - This error is implying that the Mesh Transport Layer (MTL or MTP) has a payload of less than 9 bytes.
  - Message Authentication Code (MAC) is 8 bytes and Time to live (TTL) is 1 byte.
- HML payload is not available
  - This error indicates that MTP payload contains MAC and TTL but HLM payload is missing or is 0 bytes.
- MCP data has no encrypted payload
  - This error indicates that the MCP payload contains the nonce (sequence number and source address) but encrypted payload is missing from the packet.

Bluetooth technology using mesh networking Errors

Errors: Bluetooth technology using mesh networking
Error	Description
"Reserved" Opcode	This is most likely the scenario when incorrect keys have been entered. Correct the keys in the MeshOptions.ini file and reload decoders.
Possible error in net decryption	Possible error in net decryption
Possible error in app decryption	Possible error in app decryption