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

@@ -9,7 +9,14 @@ import {
     type MACHeader,
     ZigbeeMACConsts,
 } from "../zigbee/mac.js";
-import { GlobalTlv, GlobalTlvConsts, readZigbeeTlvs } from "../zigbee/tlvs.js";
+import {
+    GlobalTlv,
+    KeyNegotationProtocol,
+    KeyNegotationProtocolMask,
+    type PreSharedSecret,
+    PreSharedSecretMask,
+    readZigbeeTlvs,
+} from "../zigbee/tlvs.js";
 import { ZigbeeConsts, ZigbeeKeyType, type ZigbeeSecurityHeader, ZigbeeSecurityLevel } from "../zigbee/zigbee.js";
 import {
     encodeZigbeeNWKFrame,
@@ -34,6 +41,13 @@ const NS = "nwk-handler";
 export interface NWKHandlerCallbacks {
     /** Send APS TRANSPORT_KEY for network key */
     onAPSSendTransportKeyNWK: (destination16: number, networkKey: Buffer, keySequenceNumber: number, destination64: bigint) => Promise<void>;
+    /** Send APS ZDO START_KEY_UPDATE_REQUEST */
+    onAPSSendStartKeyUpdateRequest: (
+        nwkDest16: number,
+        nwkDest64: bigint,
+        keyNegotiationProtocol: KeyNegotationProtocol,
+        preSharedSecret: PreSharedSecret,
+    ) => Promise<void>;
 }
 
 /** The number of OctetDurations until a route discovery expires. */
@@ -1300,15 +1314,15 @@ export class NWKHandler {
                     status = MACAssociationStatus.PAN_FULL;
                 } else {
                     status = ZigbeeNWKConsts.ASSOC_STATUS_ADDR_CONFLICT;
-                    requiresTransportKey = !secured;
+                    requiresTransportKey = !secured; // only if Trust Center Rejoin
                     const neighbor = macHeader.source16 === nwkHeader.source16;
 
                     await this.#context.associate(newAddress16, nwkHeader.source64, decodedCap, neighbor, false);
                 }
             } else {
                 newAddress16 = nwkHeader.source16;
                 status = MACAssociationStatus.SUCCESS;
-                requiresTransportKey = !secured;
+                requiresTransportKey = !secured; // only if Trust Center Rejoin
                 const neighbor = macHeader.source16 === nwkHeader.source16;
 
                 await this.#context.associate(newAddress16, nwkHeader.source64, decodedCap, neighbor, false);
@@ -1318,7 +1332,7 @@ export class NWKHandler {
         await this.sendRejoinResp(nwkHeader.source16, newAddress16, status);
 
         if (requiresTransportKey) {
-            // XXX: is this spec?
+            // XXX: use tunnel even if direct Coordinator<>rejoiner?
             await this.#callbacks.onAPSSendTransportKeyNWK(
                 newAddress16,
                 this.#context.netParams.networkKey,
@@ -1878,8 +1892,9 @@ export class NWKHandler {
         const commissioningType = data.readUInt8(offset);
         offset += 1;
         const secured = nwkHeader.frameControl.security;
+        const initialJoin = commissioningType === ZigbeeNWKCommissioningType.INITIAL_JOIN;
 
-        if (secured && commissioningType === ZigbeeNWKCommissioningType.INITIAL_JOIN) {
+        if (secured && initialJoin) {
             return; // per spec, drop
         }
 
@@ -1888,30 +1903,39 @@ export class NWKHandler {
         const decodedCap = decodeMACCapabilities(capabilities);
         const [globalTlvs] = readZigbeeTlvs(data, offset);
         const joinerTlv = globalTlvs[GlobalTlv.JOINER_ENCAPSULATION];
-        let selectedKeyNegotiationMethod = GlobalTlvConsts.KEY_NEGOTATION_METHOD_STATIC; // fallback
 
-        if (joinerTlv !== undefined) {
-            // device is R23
-            const fragmentationParametersTlv = joinerTlv.additionalTlvs[GlobalTlv.FRAGMENTATION_PARAMETERS];
-            const supportedKeyNegotiationMethodsTlv = joinerTlv.additionalTlvs[GlobalTlv.SUPPORTED_KEY_NEGOTIATION_METHODS];
+        if (joinerTlv === undefined) {
+            return; // invalid
+        }
+
+        const supportedKeyNegotiationMethodsTlv = joinerTlv.additionalTlvs[GlobalTlv.SUPPORTED_KEY_NEGOTIATION_METHODS];
+        const rejoin = commissioningType === ZigbeeNWKCommissioningType.REJOIN;
 
-            if (fragmentationParametersTlv !== undefined) {
-                // TODO
+        if (supportedKeyNegotiationMethodsTlv === undefined) {
+            if (!rejoin) {
+                return; // invalid
+            }
+        } else {
+            // TODO: support other protocols
+            if (!(supportedKeyNegotiationMethodsTlv.keyNegotiationProtocolsBitmask & KeyNegotationProtocolMask.Z3)) {
+                return; // per spec, must always be supported
             }
 
-            if (supportedKeyNegotiationMethodsTlv !== undefined) {
-                // TODO
-                const bitmask = supportedKeyNegotiationMethodsTlv.keyNegotiationProtocolsBitmask;
+            if (!(supportedKeyNegotiationMethodsTlv.preSharedSecretsBitmask & PreSharedSecretMask.INSTALL_CODE_KEY)) {
+                // XXX: spec?
+                await this.sendCommissioningResponse(nwkHeader.source16, 0xffff, MACAssociationStatus.PAN_ACCESS_DENIED);
 
-                // TODO: by order of "most security"?
-                if (bitmask & GlobalTlvConsts.KEY_NEGOTATION_METHOD_SHA256) {
-                    selectedKeyNegotiationMethod = GlobalTlvConsts.KEY_NEGOTATION_METHOD_SHA256;
-                } else if (bitmask & GlobalTlvConsts.KEY_NEGOTATION_METHOD_MMO128) {
-                    selectedKeyNegotiationMethod = GlobalTlvConsts.KEY_NEGOTATION_METHOD_MMO128;
-                }
+                return; // others currently not supported
             }
         }
 
+        // TODO: store in state?
+        const fragmentationParametersTlv = joinerTlv.additionalTlvs[GlobalTlv.FRAGMENTATION_PARAMETERS];
+
+        if (fragmentationParametersTlv === undefined) {
+            return; // invalid
+        }
+
         logger.debug(
             () =>
                 `<=== NWK COMMISSIONING_REQUEST[macSrc=${macHeader.source16}:${macHeader.source64} nwkSrc=${nwkHeader.source16}:${nwkHeader.source64} sec=${secured} type=${commissioningType} cap=${capabilities}]`,
@@ -1924,8 +1948,8 @@ export class NWKHandler {
         let status: MACAssociationStatus | number = MACAssociationStatus.PAN_ACCESS_DENIED;
         let requiresTransportKey = false;
 
-        if (commissioningType === ZigbeeNWKCommissioningType.INITIAL_JOIN) {
-            if (this.#context.trustCenterPolicies.allowJoins) {
+        if (initialJoin) {
+            if (this.#context.macAssociationPermit && this.#context.trustCenterPolicies.allowJoins) {
                 if (this.#context.address16ToAddress64.has(nwkHeader.source16)) {
                     // device address is conflicting, assign new one
                     newAddress16 = this.#context.assignNetworkAddress();
@@ -1948,7 +1972,7 @@ export class NWKHandler {
                     await this.#context.associate(newAddress16, nwkHeader.source64, decodedCap, neighbor, true);
                 }
             }
-        } else if (commissioningType === ZigbeeNWKCommissioningType.REJOIN) {
+        } else if (rejoin) {
             const device = this.#context.deviceTable.get(nwkHeader.source64);
 
             if (device?.authorized) {
@@ -1961,15 +1985,15 @@ export class NWKHandler {
                         status = MACAssociationStatus.PAN_FULL;
                     } else {
                         status = ZigbeeNWKConsts.ASSOC_STATUS_ADDR_CONFLICT;
-                        requiresTransportKey = !secured;
+                        requiresTransportKey = !secured; // only if Trust Center Rejoin
                         const neighbor = macHeader.source16 === nwkHeader.source16;
 
                         await this.#context.associate(newAddress16, nwkHeader.source64, decodedCap, neighbor, false);
                     }
                 } else {
                     newAddress16 = nwkHeader.source16;
                     status = MACAssociationStatus.SUCCESS;
-                    requiresTransportKey = !secured;
+                    requiresTransportKey = !secured; // only if Trust Center Rejoin
                     const neighbor = macHeader.source16 === nwkHeader.source16;
 
                     await this.#context.associate(newAddress16, nwkHeader.source64, decodedCap, neighbor, false);
@@ -1980,21 +2004,29 @@ export class NWKHandler {
         await this.sendCommissioningResponse(nwkHeader.source16, newAddress16, status);
 
         if (requiresTransportKey) {
-            // TODO: might need to be different if R23 or not
-            if (selectedKeyNegotiationMethod === GlobalTlvConsts.KEY_NEGOTATION_METHOD_STATIC) {
-                const dest64 = this.#context.address16ToAddress64.get(newAddress16);
-
-                if (dest64 !== undefined && requiresTransportKey) {
-                    await this.#callbacks.onAPSSendTransportKeyNWK(
-                        newAddress16,
-                        this.#context.netParams.networkKey,
-                        this.#context.netParams.networkKeySequenceNumber,
-                        dest64,
-                    );
-                    this.#context.markNetworkKeyTransported(dest64);
-                }
+            if (this.#context.trustCenterPolicies.keyNegotiationProtocol === KeyNegotationProtocol.Z3) {
+                await this.#callbacks.onAPSSendTransportKeyNWK(
+                    newAddress16,
+                    this.#context.netParams.networkKey,
+                    this.#context.netParams.networkKeySequenceNumber,
+                    nwkHeader.source64,
+                );
+                this.#context.markNetworkKeyTransported(nwkHeader.source64);
             } else {
-                // TODO START_KEY_UPDATE ZDO
+                if (rejoin) {
+                    // At this time this Revision of the specification does not support negotiating a new link key during rejoin.
+                    // Therefore, devices certified to this Revision SHALL not include the Supported Key Negotiation Methods Global TLV
+                    // inside the Joiner Encapsulation TLV so it is clear to the Trust Center that the device does not support this behavior.
+                    // Future revisions of this specification that support this would include this TLV as a clear sign the rejoining device supports this new functionality.
+                    return;
+                }
+
+                await this.#callbacks.onAPSSendStartKeyUpdateRequest(
+                    newAddress16,
+                    nwkHeader.source64,
+                    this.#context.trustCenterPolicies.keyNegotiationProtocol,
+                    this.#context.trustCenterPolicies.preSharedSecret,
+                );
             }
         }
     }
@@ -2029,7 +2061,7 @@ export class NWKHandler {
             false, // nwkSecurity
             ZigbeeConsts.COORDINATOR_ADDRESS, // nwkSource16
             requestSource16, // nwkDest16
-            this.#context.address16ToAddress64.get(requestSource16), // nwkDest64
+            this.#context.address16ToAddress64.get(newAddress16), // nwkDest64
             CONFIG_NWK_MAX_HOPS, // nwkRadius
         );
     }

src/zigbee-stack/nwk-handler.ts

@@ -1,6 +1,7 @@
 import { readFile, rm, writeFile } from "node:fs/promises";
 import { logger } from "../utils/logger.js";
 import { decodeMACCapabilities, encodeMACCapabilities, type MACCapabilities, type MACHeader } from "../zigbee/mac.js";
+import { KeyNegotationProtocol, PreSharedSecret } from "../zigbee/tlvs.js";
 import {
     aes128MmoHash,
     computeInstallCodeCRC,
@@ -100,6 +101,10 @@ export type TrustCenterPolicies = {
      * A setting of FALSE means rejoins are only allowed with trust center link keys where the KeyAttributes of the apsDeviceKeyPairSet entry indicates VERIFIED_KEY.
      */
     allowRejoinsWithWellKnownKey: boolean;
+    /** R23+ */
+    keyNegotiationProtocol: KeyNegotationProtocol;
+    /** R23+ */
+    preSharedSecret: PreSharedSecret;
     /** This value controls whether devices are allowed to request a Trust Center Link Key after they have joined the network. */
     allowTCKeyRequest: TrustCenterKeyRequestPolicy;
     /** This policy indicates whether a node on the network that transmits a ZDO Mgmt_Permit_Join with a significance set to 1 is allowed to effect the local Trust Center’s policies. */
@@ -389,6 +394,10 @@ export class StackContext {
         allowJoins: false,
         installCode: InstallCodePolicy.NOT_REQUIRED,
         allowRejoinsWithWellKnownKey: true,
+        // TODO: support other protocols
+        keyNegotiationProtocol: KeyNegotationProtocol.Z3,
+        // TODO: support other secrets
+        preSharedSecret: PreSharedSecret.INSTALL_CODE_KEY,
         allowTCKeyRequest: TrustCenterKeyRequestPolicy.ALLOWED,
         networkKeyUpdatePeriod: 0, // disable
         networkKeyUpdateMethod: NetworkKeyUpdateMethod.BROADCAST,

src/zigbee-stack/stack-context.ts

@@ -1,12 +1,6 @@
 import type { RequiredNonNullable } from "../utils/types.js";
 import { ZigbeeConsts } from "./zigbee.js";
 
-export const enum GlobalTlvConsts {
-    KEY_NEGOTATION_METHOD_STATIC = 0b000,
-    KEY_NEGOTATION_METHOD_MMO128 = 0b010,
-    KEY_NEGOTATION_METHOD_SHA256 = 0b100,
-}
-
 export const enum GlobalTlv {
     /** minLen=2 */
     MANUFACTURER_SPECIFIC = 64,
@@ -33,6 +27,41 @@ export const enum GlobalTlv {
     // Reserved = 77-255
 }
 
+/** uint8 */
+export const enum KeyNegotationProtocol {
+    Z3 = 0x0,
+    MMO128 = 0x1,
+    SHA256 = 0x2,
+}
+
+/** uint8 */
+export const enum KeyNegotationProtocolMask {
+    Z3 = 0b01,
+    MMO128 = 0b10,
+    SHA256 = 0b11,
+}
+
+/** uint8 */
+export const enum PreSharedSecret {
+    SYMMETRIC_AUTHENTICATION_TOKEN = 0x00,
+    INSTALL_CODE_KEY = 0x01,
+    PASSCODE_KEY = 0x02,
+    BASIC_ACCESS_KEY = 0x03,
+    ADMINISTRATIVE_ACCESS_KEY = 0x04,
+    // 0x04-0xfe reserved
+    ANONYMOUS_WELL_KNOWN_SECRET = 0xff,
+}
+
+/** uint8 */
+export const enum PreSharedSecretMask {
+    SYMMETRIC_AUTHENTICATION_TOKEN = 0b00001,
+    INSTALL_CODE_KEY = 0b00010,
+    PASSCODE_KEY = 0b00100,
+    BASIC_ACCESS_KEY = 0b01000,
+    ADMINISTRATIVE_ACCESS_KEY = 0b10000,
+    // others reserved
+}
+
 type GlobalTlvEncapsulated = {
     additionalTlvs: ZigbeeGlobalTlvs;
     additionalLocalTlvs: Map<number, Buffer>;
@@ -406,6 +435,7 @@ export function readZigbeeTlvs(data: Buffer, offset: number, parent?: number): [
     return [globalTlvs, localTlvs, offset];
 }
 
+/** Byte length: 12 */
 export function writeZigbeeTlvSupportedKeyNegotiationMethods(
     data: Buffer,
     offset: number,
@@ -420,6 +450,7 @@ export function writeZigbeeTlvSupportedKeyNegotiationMethods(
     return offset;
 }
 
+/** Byte length: 7 */
 export function writeZigbeeTlvFragmentationParameters(
     data: Buffer,
     offset: number,
@@ -434,6 +465,7 @@ export function writeZigbeeTlvFragmentationParameters(
     return offset;
 }
 
+/** Byte length: 4 */
 export function writeZigbeeTlvRouterInformation(data: Buffer, offset: number, tlv: RequiredNonNullable<GlobalTlvRouterInformation>): number {
     offset = data.writeUInt8(GlobalTlv.ROUTER_INFORMATION, offset);
     offset = data.writeUInt8(1, offset); // per spec, actual data length is `length field + 1`

src/zigbee/tlvs.ts

@@ -27,6 +27,7 @@ export const enum ZigbeeConsts {
     //---- ZDO
     ZDO_ENDPOINT = 0x00,
     ZDO_PROFILE_ID = 0x0000,
+    ZDO_SUCCESS = 0x00,
     NETWORK_ADDRESS_REQUEST = 0x0000,
     IEEE_ADDRESS_REQUEST = 0x0001,
     NODE_DESCRIPTOR_REQUEST = 0x0002,
@@ -37,6 +38,8 @@ export const enum ZigbeeConsts {
     LQI_TABLE_REQUEST = 0x0031,
     ROUTING_TABLE_REQUEST = 0x0032,
     NWK_UPDATE_REQUEST = 0x0038,
+    START_KEY_UPDATE_REQUEST = 0x0045,
+    START_KEY_UPDATE_RESPONSE = 0x8045,
 
     //---- Green Power
     GP_ENDPOINT = 0xf2,

src/zigbee/zigbee.ts

@@ -107,6 +107,7 @@ describe("Zigbee 4.0 Application Support (APS) Layer Compliance", () => {
         };
         mockNWKHandlerCallbacks = {
             onAPSSendTransportKeyNWK: vi.fn(),
+            onAPSSendStartKeyUpdateRequest: vi.fn(),
         };
         mockNWKGPHandlerCallbacks = {
             onGPFrame: vi.fn(),