fix: network commissioning

Author: Nerivec

src/drivers/ot-rcp-driver.ts

@@ -133,6 +133,9 @@ export class OTRCPDriver {
             onAPSSendTransportKeyNWK: async (address16, key, keySeqNum, destination64) => {
                 await this.apsHandler.sendTransportKeyNWK(address16, key, keySeqNum, destination64);
             },
+            onAPSSendStartKeyUpdateRequest: async (nwkDest16, nwkDest64, keyNegotiationProtocol, preSharedSecret) => {
+                await this.apsHandler.sendStartKeyUpdateRequest(nwkDest16, nwkDest64, keyNegotiationProtocol, preSharedSecret);
+            },
         };
 
         this.nwkHandler = new NWKHandler(this.context, this.macHandler, nwkCallbacks);

src/zigbee-stack/aps-handler.ts

@@ -8,7 +8,13 @@ import {
     type MACHeader,
     ZigbeeMACConsts,
 } from "../zigbee/mac.js";
-import { GlobalTlv, readZigbeeTlvs } from "../zigbee/tlvs.js";
+import {
+    GlobalTlv,
+    type KeyNegotationProtocol,
+    type PreSharedSecret,
+    readZigbeeTlvs,
+    writeZigbeeTlvFragmentationParameters,
+} from "../zigbee/tlvs.js";
 import { ZigbeeConsts, ZigbeeKeyType, type ZigbeeSecurityHeader, ZigbeeSecurityLevel } from "../zigbee/zigbee.js";
 import {
     decodeZigbeeAPSFrameControl,
@@ -1053,57 +1059,78 @@ export class APSHandler {
                 );
 
                 if (apsHeader.profileId === ZigbeeConsts.ZDO_PROFILE_ID) {
-                    if (apsHeader.clusterId === ZigbeeConsts.END_DEVICE_ANNOUNCE) {
-                        let offset = 1; // skip seq num
-                        const address16 = data.readUInt16LE(offset);
-                        offset += 2;
-                        const address64 = data.readBigUInt64LE(offset);
-                        offset += 8;
-                        const capabilities = data.readUInt8(offset);
-                        offset += 1;
-
-                        const device = this.#context.deviceTable.get(address64);
-
-                        if (device === undefined) {
-                            // unknown device, should have been added by `associate`, something's not right, ignore it
-                            return;
-                        }
+                    switch (apsHeader.clusterId) {
+                        case ZigbeeConsts.END_DEVICE_ANNOUNCE: {
+                            let offset = 1; // skip seq num
+                            const address16 = data.readUInt16LE(offset);
+                            offset += 2;
+                            const address64 = data.readBigUInt64LE(offset);
+                            offset += 8;
+                            const capabilities = data.readUInt8(offset);
+                            offset += 1;
+
+                            const device = this.#context.deviceTable.get(address64);
+
+                            if (device === undefined) {
+                                // unknown device, should have been added by `associate`, something's not right, ignore it
+                                return;
+                            }
 
-                        const decodedCap = decodeMACCapabilities(capabilities);
+                            const decodedCap = decodeMACCapabilities(capabilities);
 
-                        if (device.address16 !== address16) {
-                            this.#context.address16ToAddress64.delete(device.address16);
-                            this.#context.address16ToAddress64.set(address16, address64);
+                            if (device.address16 !== address16) {
+                                // change of address
+                                this.#context.address16ToAddress64.delete(device.address16);
+                                this.#context.address16ToAddress64.set(address16, address64);
 
-                            device.address16 = address16;
-                        }
+                                device.address16 = address16;
+                            }
 
-                        // just in case
-                        device.capabilities = decodedCap;
+                            // just in case
+                            device.capabilities = decodedCap;
 
-                        await this.#context.savePeriodicState();
+                            await this.#context.savePeriodicState();
 
-                        // TODO: ideally, this shouldn't trigger (prevents early interview process from app) until AFTER authorized=true
-                        setImmediate(() => {
-                            // if device is authorized, it means it completed the TC link key update, so, a rejoin
-                            // TODO: could flip authorized to true before the announce and count as rejoin when it shouldn't
-                            if (device.authorized) {
-                                this.#callbacks.onDeviceRejoined(address16, address64, decodedCap);
-                            } else {
-                                this.#callbacks.onDeviceJoined(address16, address64, decodedCap);
-                            }
-                        });
-                    } else {
-                        const isRequest = (apsHeader.clusterId! & 0x8000) === 0;
+                            // TODO: ideally, this shouldn't trigger (prevents early interview process from app) until AFTER authorized=true
+                            setImmediate(() => {
+                                // if device is authorized, it means it completed the TC link key update, so, a rejoin
+                                // TODO: could flip authorized to true before the announce and count as rejoin when it shouldn't
+                                if (device.authorized) {
+                                    this.#callbacks.onDeviceRejoined(address16, address64, decodedCap);
+                                } else {
+                                    this.#callbacks.onDeviceJoined(address16, address64, decodedCap);
+                                }
+                            });
 
-                        if (isRequest) {
-                            if (this.isZDORequestForCoordinator(apsHeader.clusterId!, nwkHeader.destination16, nwkHeader.destination64, data)) {
-                                await this.respondToCoordinatorZDORequest(data, apsHeader.clusterId!, nwkHeader.source16, nwkHeader.source64);
+                            break;
+                        }
+                        case ZigbeeConsts.START_KEY_UPDATE_RESPONSE: {
+                            // skip seq num
+                            const status = data.readUInt8(1);
+
+                            if (status !== ZigbeeConsts.ZDO_SUCCESS) {
+                                // failed security, cleanup
+                                await this.#context.disassociate(nwkHeader.source16, nwkHeader.source64);
                             }
 
-                            // don't emit received ZDO requests
+                            // handled internally, don't emit
+                            return;
+                        }
+                        case undefined: {
                             return;
                         }
+                        default: {
+                            const isRequest = (apsHeader.clusterId & 0x8000) === 0;
+
+                            if (isRequest) {
+                                if (this.isZDORequestForCoordinator(apsHeader.clusterId, nwkHeader.destination16, nwkHeader.destination64, data)) {
+                                    await this.respondToCoordinatorZDORequest(data, apsHeader.clusterId, nwkHeader.source16, nwkHeader.source64);
+                                }
+
+                                // don't emit received ZDO requests
+                                return;
+                            }
+                        }
                     }
                 }
 
@@ -2169,6 +2196,60 @@ export class APSHandler {
 
     // NOTE: sendRelayMessageUpstream DEVICE SCOPE: [unauthorized] routers (N/A), end devices (N/A)
 
+    /**
+     * 06-3474-23 #4.4.9.1 APSME-KEY-NEGOTIATION.request
+     *
+     * SPEC COMPLIANCE:
+     * - TODO
+     *
+     * DEVICE SCOPE: Trust Center
+     */
+    public async sendStartKeyUpdateRequest(
+        nwkDest16: number,
+        nwkDest64: bigint,
+        keyNegotiationProtocol: KeyNegotationProtocol,
+        preSharedSecret: PreSharedSecret,
+    ): Promise<boolean> {
+        const ackHeader: ZigbeeAPSHeader = {
+            frameControl: {
+                frameType: ZigbeeAPSFrameType.DATA,
+                deliveryMode: ZigbeeAPSDeliveryMode.UNICAST,
+                ackFormat: false,
+                security: false,
+                ackRequest: true,
+                extendedHeader: false,
+            },
+            destEndpoint: ZigbeeConsts.ZDO_ENDPOINT,
+            clusterId: ZigbeeConsts.START_KEY_UPDATE_REQUEST,
+            profileId: ZigbeeConsts.ZDO_PROFILE_ID,
+            sourceEndpoint: ZigbeeConsts.ZDO_ENDPOINT,
+            counter: this.nextCounter(),
+        };
+        const apsPayload = Buffer.allocUnsafe(20);
+        let offset = 0;
+        offset = apsPayload.writeUInt8(this.nextZDOSeqNum(), offset);
+        // local TLV: Selected Key Negotiation Method
+        offset = apsPayload.writeUInt8(0x00, offset);
+        offset = apsPayload.writeUInt8(9, offset); // per spec, actual data length is `length field + 1`
+        offset = apsPayload.writeUInt8(keyNegotiationProtocol, offset);
+        offset = apsPayload.writeUInt8(preSharedSecret, offset);
+        offset = apsPayload.writeBigUInt64LE(this.#context.netParams.eui64, offset);
+        writeZigbeeTlvFragmentationParameters(apsPayload, offset, {
+            nwkAddress: ZigbeeConsts.COORDINATOR_ADDRESS,
+            fragmentationOptions: 0b1,
+            maxIncomingTransferUnit: ZigbeeMACConsts.FRAME_MAX_SIZE,
+        });
+
+        const apsFrame = encodeZigbeeAPSFrame(
+            ackHeader,
+            apsPayload,
+            // undefined,
+            // undefined,
+        );
+
+        return await this.sendRelayMessageDownstream(nwkDest16, nwkDest64, nwkDest64, apsFrame);
+    }
+
     // #endregion
 
     // #region ZDO Helpers