Zigbee 3.0 device secure provisioning via QR code scanning for ZHA integration?

[Hedda]

Secured device inclusion by QR code scan feature with Z-Wave SmartStart provisioning added awesome streamlining experience for users:

@bramkragten wrote in #10726 that the QR scanner part would be a separate reusable element that could also be reused for ZHA or others.

Wondering if we could get a similar QR code scan feature for secure provisioning of Zigbee 3.0 devices for ZHA integration in HA frontend?

As I understand the needed backend support for “qr_code” and “install_code” is already available Home Assistant core for the ZHA integration component with the “zha.permit" service allowing Zigbee 3.0 devices to securely join the Zigbee network if the vendors install code printed on products can be parsed from their QR code.

home-assistant/core#40652 (in that PR it was asked by the submitting developer if QR code scanning could be implemented into ZHA UI).

Zigbee 3.0 (ZB3) support secured "quick-start" joining/pairing in ZHA integration component using qr_code and install_code parameters.

https://www.home-assistant.io/integrations/zha/#services

This Zigbee 3.0 feature is already available in the frontend for a few commercial gateways/hubs such as Samsung SmartThings and Tuya.

https://youtu.be/odU93fb99hc?t=66

https://www.androidpolice.com/2020/08/26/samsung-smartthings-update-adds-uwb-device-tracking-zigbee-qr-scanner-and-more/

https://developer.tuya.com/en/docs/iot/user-manual-for-tuya-smart-v3177?id=K9obrofrfk4sk#title-19-Scan%20QR%20codes%20or%20enter%20device%20IDs%20to%20add%20NB-IoT%20devices

https://developer.tuya.com/en/docs/iot/user-manual-for-tuya-smart-v3177?id=K9obrofrfk4sk#title-20-Add%20devices%20by%20scanning%20QR%20codes

The QR code can be used for device inclusion and activation via IEEE address (as a kind of UUID value) for secured joining/pairing with compatible systems that support this Zigbee 3.0 feature. These QR codes or bar codes should be printed on newer Zigbee 3.0 (ZB3) certified products in order to make adding new devices both more user-friendly and more provisioning for device inclusion secure.

Enabling this could allow users to open Home Assistant’s UI or companion app on Android/iOS, scan the QR code of the Zigbee 3.0 device or its box to initiate device joining/pairing in Home Assistant ZHA in order to achieve highest security possible for device connections.

This Zigbee device QR code for pairing/joining is a ‘newish’ (part of official Zigbee 3.0 specification since 2016) feature that is part of Zigbee 3.0 security model specification which allow users to add devices to their Zigbee network by scanning quick response QR codes (a.k.a. two-dimensional barcodes or 2D barcode) which contains Zigbee installation codes, (sometimes also referred to as “install codes”), which is the devices 64-bit IEEE MAC address (“EUI64”).

Again, this only works with Zigbee 3.0 certified devices and products with printed QR code that contain device IEEE MAC address.

Note that this also requires a Zigbee 3.0 coordinator hardware with firmware compatible with Home Assistant as well as support for Zigbee 3.0 joining via install codes in the zigpy radio library, which so far is only supported in zigpy's bellows and zigpy-znp libraries.

https://www.home-assistant.io/integrations/zha/#services

Services

Service zha.permit

To add new devices to the network, call the permit service on the zha domain. Do this by clicking the Service icon in Developer tools and typing zha.permit in the Service dropdown box. Next, follow the device instructions for adding, scanning or factory reset.

This service opens network for joining new devices.

Data	Optional	Description
duration	yes	For how long to allow new devices to join, default 60s
ieee	yes	allow new devices to join via an existing device

To join a new device using an install code (ZB3 devices) use the following data attributes (must use parameters only
from the same group:

Data	Parameter Group	Description
src_ieee	install_code	The IEEE address of the joining ZB3 device. Use with install_code
install_code	install_code	Install Code of the joining device. Use with src_ieee
qr_code	qr_code	QR code containing IEEE and Install Code of the joining ZB3 device

Currently qr_code supports QR Install Codes from:

• Aqara
• Bosch
• Consciot
• Embrighten

PS: Bote that the backend may need to be extended with more vendor-specific parsers in order to get the correct install code from QR code.

LEDVANCE and OSRAM are two other manufacturers who provides QR code provisioning for joining Zigbee 3.0 compatible devices via official smart phone apps for their propriatory gatewats , they are marketing their implementation of this Zigbee 3.0 feature as “SMART+”:

https://images-eu.ssl-images-amazon.com/images/I/81GMA0osNCS.pdf 3

https://www.ledvance.com/consumer/smart/index.jsp

TaHoma is another:

https://si-website-files.s3.amazonaws.com/Downloads/Installation+Instructions/Accessories/tahoma-app-quick-start-guide.pdf

[Hedda]

Currently qr_code supports QR Install Codes from:

• Aqara
• Consciot
• Embrighten

Note that qr_code is experimental and since every vendor encodes ieee and install code differently, this would need to be added to the backend for every vendor, assuming it can be matched by a regex.

Quote from https://www.openhab.org/addons/bindings/zigbee/

ZigBee 3.0 requires that devices use an install code to securely join the network. This must be added to the binding before the discovery starts. Install codes should be printed on the box the device came in, or possibly on the device itself. Note that there is no standard format for how these codes may be displayed on the device or its packaging. You may need to use a QR reader to read the code - again these are not standard in their format, although you should be able to find the address and install code in the displayed text.

The install code must be entered into the coordinator settings before starting the discovery process. The format is IEEE Address:Install Code in the following format -:

AAAAAAAAAAAAAAAA:CCCC-CCCC-CCCC-CCCC-CCCC-CCCC-CCCC-CCCC-DDDD

ZigBee 3.0 requires the install code to be 16 bytes long (8 blocks of characters) but some older systems using this method may use less bytes, but it should still be formatted as 2, 4, or 8 groups of 4 values. Note that the last four characters in the install code are the checksum and may be provided separately.

Silicon Labs EFR32 Mighy Gecko / Wireless Gecko EmberZNet reference:

• https://www.silabs.com/documents/public/application-notes/an1089-using-installation-codes-with-zigbee-devices.pdf

What Is an Installation Code?

Zigbee installation codes, sometimes also referred to as “install codes,” are provided as a means for a device to join a Zigbee network in a reasonably secure fashion. The installation code itself is a random value installed on the joining device at manufacturing time, and is used to encrypt the initial network key transport from the Zigbee network’s centralized Trust Center device (the coordinator) to the joining device. With the creation of the Zigbee 3.0 standard in late 2016, all Zigbee devices capable of joining networks (as opposed to forming them) must support the use of installation codes during joining, as this is a requirement for Zigbee 3.0 compliance.

The installation code can be thought of as similar to the PIN code on Bluetooth devices when two devices are paired. The PIN code is provided as an authorization code for the parent device so that the joining device knows it is receiving information securely, such as when a hands-free headset is paired to a smartphone.

The installation code is typically printed on the case or packaging of the device, either as a hexadecimal string or in an encoded fashion such as a barcode or QR code, and provided through an out-of-band mechanism to the Trust Center device or its associated web/cloud interface, along with the 64-bit IEEE MAC address (“EUI64”) of the device. If this device-specific data is stored on a remote web server or cloud-based system, that remote system then securely transports that information to the Trust Center to establish security credentials for the joining device in advance of the in-band joining process.