@zwave-js/cc 14.1.0 → 14.2.0

package/build/esm/cc/Security2CC.js

@@ -922,6 +922,7 @@ let Security2CCMessageEncapsulation = (() => {
                 throw new ZWaveError("Multicast Security S2 encapsulation requires the MGRP extension", ZWaveErrorCodes.Security2CC_MissingExtension);
             }
         }
+        /** @deprecated Use {@link fromAsync} instead */
         static from(raw, ctx) {
             const securityManager = assertSecurityRX(ctx);
             validatePayload(raw.payload.length >= 2);
@@ -1131,6 +1132,7 @@ let Security2CCMessageEncapsulation = (() => {
                 // make sure this contains a complete CC command that's worth splitting
                 validatePayload(decryptedCCBytes.length >= 2);
                 // and deserialize the CC
+                // eslint-disable-next-line @typescript-eslint/no-deprecated
                 encapsulated = CommandClass.parse(decryptedCCBytes, ctx);
             }
             const ret = new Security2CCMessageEncapsulation({
@@ -1148,6 +1150,232 @@ let Security2CCMessageEncapsulation = (() => {
             ret.plaintext = decryptedCCBytes;
             return ret;
         }
+        static async fromAsync(raw, ctx) {
+            const securityManager = assertSecurityRX(ctx);
+            validatePayload(raw.payload.length >= 2);
+            // Check the sequence number to avoid duplicates
+            const sequenceNumber = raw.payload[0];
+            // Ensure the node has a security class
+            validatePayload.withReason("No security class granted")(ctx.getHighestSecurityClass(ctx.sourceNodeId) !== SecurityClass.None);
+            const hasExtensions = !!(raw.payload[1] & 0b1);
+            const hasEncryptedExtensions = !!(raw.payload[1] & 0b10);
+            let offset = 2;
+            const extensions = [];
+            let mustDiscardCommand = false;
+            const parseExtensions = (buffer, wasEncrypted) => {
+                while (true) {
+                    if (buffer.length < offset + 2) {
+                        // An S2 extension was expected, but the buffer is too short
+                        mustDiscardCommand = true;
+                        return;
+                    }
+                    // The length field could be too large, which would cause part of the actual ciphertext
+                    // to be ignored. Try to avoid this for known extensions by checking the actual and expected length.
+                    const { actual: actualLength, expected: expectedLength } = Security2Extension
+                        .getExtensionLength(buffer.subarray(offset));
+                    // Parse the extension using the expected length if possible
+                    const extensionLength = expectedLength ?? actualLength;
+                    if (extensionLength < 2) {
+                        // An S2 extension was expected, but the length is too short
+                        mustDiscardCommand = true;
+                        return;
+                    }
+                    else if (extensionLength
+                        > buffer.length
+                            - offset
+                            - (wasEncrypted
+                                ? 0
+                                : SECURITY_S2_AUTH_TAG_LENGTH)) {
+                        // The supposed length is longer than the space the extensions may occupy
+                        mustDiscardCommand = true;
+                        return;
+                    }
+                    const extensionData = buffer.subarray(offset, offset + extensionLength);
+                    offset += extensionLength;
+                    const ext = Security2Extension.parse(extensionData);
+                    switch (validateS2Extension(ext, wasEncrypted)) {
+                        case ValidateS2ExtensionResult.OK:
+                            if (expectedLength != undefined
+                                && actualLength !== expectedLength) {
+                                // The extension length field does not match, ignore the extension
+                            }
+                            else {
+                                extensions.push(ext);
+                            }
+                            break;
+                        case ValidateS2ExtensionResult.DiscardExtension:
+                            // Do nothing
+                            break;
+                        case ValidateS2ExtensionResult.DiscardCommand:
+                            mustDiscardCommand = true;
+                            break;
+                    }
+                    // Check if that was the last extension
+                    if (!ext.moreToFollow)
+                        break;
+                }
+            };
+            if (hasExtensions)
+                parseExtensions(raw.payload, false);
+            const mcctx = (() => {
+                const multicastGroupId = getMulticastGroupId(extensions);
+                if (ctx.frameType === "multicast" || ctx.frameType === "broadcast") {
+                    if (multicastGroupId == undefined) {
+                        validatePayload.fail("Multicast frames without MGRP extension");
+                    }
+                    return {
+                        isMulticast: true,
+                        groupId: multicastGroupId,
+                    };
+                }
+                else {
+                    return { isMulticast: false, groupId: multicastGroupId };
+                }
+            })();
+            // If a command is to be discarded before decryption,
+            // we still need to increment the SPAN or MPAN state
+            if (mustDiscardCommand) {
+                if (mcctx.isMulticast) {
+                    securityManager.nextPeerMPAN(ctx.sourceNodeId, mcctx.groupId);
+                }
+                else {
+                    securityManager.nextNonce(ctx.sourceNodeId);
+                }
+                validatePayload.fail("Invalid S2 extension");
+            }
+            let prevSequenceNumber;
+            let mpanState;
+            if (mcctx.isMulticast) {
+                mpanState = securityManager.getPeerMPAN(ctx.sourceNodeId, mcctx.groupId);
+            }
+            else {
+                // Don't accept duplicate Singlecast commands
+                prevSequenceNumber = validateSequenceNumber(securityManager, ctx.sourceNodeId, sequenceNumber);
+                // When a node receives a singlecast message after a multicast group was marked out of sync,
+                // it must forget about the group.
+                if (mcctx.groupId == undefined) {
+                    securityManager.resetOutOfSyncMPANs(ctx.sourceNodeId);
+                }
+            }
+            const unencryptedPayload = raw.payload.subarray(0, offset);
+            const ciphertext = raw.payload.subarray(offset, -SECURITY_S2_AUTH_TAG_LENGTH);
+            const authTag = raw.payload.subarray(-SECURITY_S2_AUTH_TAG_LENGTH);
+            const messageLength = 2 /* CommandClass.computeEncapsulationOverhead() */
+                + raw.payload.length;
+            const authData = getAuthenticationData(ctx.sourceNodeId, getDestinationIDRX(ctx, extensions), ctx.homeId, messageLength, unencryptedPayload);
+            let decrypt;
+            if (mcctx.isMulticast) {
+                // For incoming multicast commands, make sure we have an MPAN
+                if (mpanState?.type !== MPANState.MPAN) {
+                    // If we don't, mark the MPAN as out of sync, so we can respond accordingly on the singlecast followup
+                    securityManager.storePeerMPAN(ctx.sourceNodeId, mcctx.groupId, { type: MPANState.OutOfSync });
+                    failNoMPAN();
+                }
+                decrypt = () => decryptMulticast(ctx.sourceNodeId, securityManager, mcctx.groupId, ciphertext, authData, authTag);
+            }
+            else {
+                // Decrypt payload and verify integrity
+                const spanState = securityManager.getSPANState(ctx.sourceNodeId);
+                // If we are not able to establish an SPAN yet, fail the decryption
+                if (spanState.type === SPANState.None) {
+                    failNoSPAN();
+                }
+                else if (spanState.type === SPANState.RemoteEI) {
+                    // TODO: The specs are not clear how to handle this case
+                    // For now, do the same as if we didn't have any EI
+                    failNoSPAN();
+                }
+                decrypt = () => decryptSinglecast(ctx, securityManager, ctx.sourceNodeId, sequenceNumber, prevSequenceNumber, ciphertext, authData, authTag, spanState, extensions);
+            }
+            let plaintext;
+            let authOK = false;
+            let key;
+            let iv;
+            let decryptionSecurityClass;
+            // If the Receiver is unable to authenticate the singlecast message with the current SPAN,
+            // the Receiver SHOULD try decrypting the message with one or more of the following SPAN values,
+            // stopping when decryption is successful or the maximum number of iterations is reached.
+            // If the Receiver is unable to decrypt the S2 MC frame with the current MPAN, the Receiver MAY try
+            // decrypting the frame with one or more of the subsequent MPAN values, stopping when decryption is
+            // successful or the maximum number of iterations is reached.
+            const decryptAttempts = mcctx.isMulticast
+                ? MAX_DECRYPT_ATTEMPTS_MULTICAST
+                : mcctx.groupId != undefined
+                    ? MAX_DECRYPT_ATTEMPTS_SC_FOLLOWUP
+                    : MAX_DECRYPT_ATTEMPTS_SINGLECAST;
+            for (let i = 0; i < decryptAttempts; i++) {
+                ({
+                    plaintext,
+                    authOK,
+                    key,
+                    iv,
+                    securityClass: decryptionSecurityClass,
+                } = decrypt());
+                if (!!authOK && !!plaintext)
+                    break;
+                // No need to try further SPANs if we just got the sender's EI
+                if (!!getSenderEI(extensions))
+                    break;
+            }
+            // If authentication fails, do so with an error code that instructs the
+            // applHost to tell the node we have no nonce
+            if (!authOK || !plaintext) {
+                if (mcctx.isMulticast) {
+                    // Mark the MPAN as out of sync
+                    securityManager.storePeerMPAN(ctx.sourceNodeId, mcctx.groupId, { type: MPANState.OutOfSync });
+                    validatePayload.fail(ZWaveErrorCodes.Security2CC_CannotDecodeMulticast);
+                }
+                else {
+                    validatePayload.fail(ZWaveErrorCodes.Security2CC_CannotDecode);
+                }
+            }
+            else if (!mcctx.isMulticast && mcctx.groupId != undefined) {
+                // After reception of a singlecast followup, the MPAN state must be increased
+                securityManager.tryIncrementPeerMPAN(ctx.sourceNodeId, mcctx.groupId);
+            }
+            // Remember which security class was used to decrypt this message, so we can discard it later
+            const securityClass = decryptionSecurityClass;
+            offset = 0;
+            if (hasEncryptedExtensions)
+                parseExtensions(plaintext, true);
+            // Before we can continue, check if the command must be discarded
+            if (mustDiscardCommand) {
+                validatePayload.fail("Invalid extension");
+            }
+            // If the MPAN extension was received, store the MPAN
+            if (!mcctx.isMulticast) {
+                const mpanExtension = extensions.find((e) => e instanceof MPANExtension);
+                if (mpanExtension) {
+                    securityManager.storePeerMPAN(ctx.sourceNodeId, mpanExtension.groupId, {
+                        type: MPANState.MPAN,
+                        currentMPAN: mpanExtension.innerMPANState,
+                    });
+                }
+            }
+            // Not every S2 message includes an encapsulated CC
+            const decryptedCCBytes = plaintext.subarray(offset);
+            let encapsulated;
+            if (decryptedCCBytes.length > 0) {
+                // make sure this contains a complete CC command that's worth splitting
+                validatePayload(decryptedCCBytes.length >= 2);
+                // and deserialize the CC
+                encapsulated = await CommandClass.parseAsync(decryptedCCBytes, ctx);
+            }
+            const ret = new Security2CCMessageEncapsulation({
+                nodeId: ctx.sourceNodeId,
+                sequenceNumber,
+                securityClass,
+                extensions,
+                encapsulated,
+            });
+            // Remember for debugging purposes
+            ret.key = key;
+            ret.iv = iv;
+            ret.authData = authData;
+            ret.authTag = authTag;
+            ret.plaintext = decryptedCCBytes;
+            return ret;
+        }
         securityClass;
         // Only used for testing/debugging purposes
         key;
@@ -1227,6 +1455,7 @@ let Security2CCMessageEncapsulation = (() => {
                 }
             }
         }
+        /** @deprecated Use {@link serializeAsync} instead */
         serialize(ctx) {
             const securityManager = assertSecurityTX(ctx, this.nodeId);
             this.ensureSequenceNumber(securityManager);
@@ -1242,6 +1471,7 @@ let Security2CCMessageEncapsulation = (() => {
                 ]),
                 ...unencryptedExtensions.map((e, index) => e.serialize(index < unencryptedExtensions.length - 1)),
             ]);
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             const serializedCC = this.encapsulated?.serialize(ctx)
                 ?? new Bytes();
             const plaintextPayload = Bytes.concat([
@@ -1285,8 +1515,69 @@ let Security2CCMessageEncapsulation = (() => {
                 ciphertextPayload,
                 authTag,
             ]);
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             return super.serialize(ctx);
         }
+        async serializeAsync(ctx) {
+            const securityManager = assertSecurityTX(ctx, this.nodeId);
+            this.ensureSequenceNumber(securityManager);
+            // Include Sender EI in the command if we only have the receiver's EI
+            this.maybeAddSPANExtension(ctx, securityManager);
+            const unencryptedExtensions = this.extensions.filter((e) => !e.isEncrypted());
+            const encryptedExtensions = this.extensions.filter((e) => e.isEncrypted());
+            const unencryptedPayload = Bytes.concat([
+                Bytes.from([
+                    this.sequenceNumber,
+                    (encryptedExtensions.length > 0 ? 0b10 : 0)
+                        | (unencryptedExtensions.length > 0 ? 1 : 0),
+                ]),
+                ...unencryptedExtensions.map((e, index) => e.serialize(index < unencryptedExtensions.length - 1)),
+            ]);
+            const serializedCC = (await this.encapsulated?.serializeAsync(ctx))
+                ?? new Bytes();
+            const plaintextPayload = Bytes.concat([
+                ...encryptedExtensions.map((e, index) => e.serialize(index < encryptedExtensions.length - 1)),
+                serializedCC,
+            ]);
+            // Generate the authentication data for CCM encryption
+            const destinationTag = getDestinationIDTX.call(this);
+            const messageLength = this.computeEncapsulationOverhead()
+                + serializedCC.length;
+            const authData = getAuthenticationData(ctx.ownNodeId, destinationTag, ctx.homeId, messageLength, unencryptedPayload);
+            let key;
+            let iv;
+            if (this.isSinglecast()) {
+                // Singlecast:
+                // Generate a nonce for encryption, and remember it to attempt decryption
+                // of potential in-flight messages from the target node.
+                iv = securityManager.nextNonce(this.nodeId, true);
+                const { keyCCM } = 
+                // Prefer the overridden security class if it was given
+                this.securityClass != undefined
+                    ? securityManager.getKeysForSecurityClass(this.securityClass)
+                    : securityManager.getKeysForNode(this.nodeId);
+                key = keyCCM;
+            }
+            else {
+                // Multicast:
+                const keyAndIV = securityManager.getMulticastKeyAndIV(destinationTag);
+                key = keyAndIV.key;
+                iv = keyAndIV.iv;
+            }
+            const { ciphertext: ciphertextPayload, authTag } = encryptAES128CCM(key, iv, plaintextPayload, authData, SECURITY_S2_AUTH_TAG_LENGTH);
+            // Remember key and IV for debugging purposes
+            this.key = key;
+            this.iv = iv;
+            this.authData = authData;
+            this.authTag = authTag;
+            this.ciphertext = ciphertextPayload;
+            this.payload = Bytes.concat([
+                unencryptedPayload,
+                ciphertextPayload,
+                authTag,
+            ]);
+            return super.serializeAsync(ctx);
+        }
         computeEncapsulationOverhead() {
             // Security S2 adds:
             // * 1 byte sequence number
@@ -1422,6 +1713,7 @@ let Security2CCNonceReport = (() => {
             if (this.SOS) {
                 this.payload = Bytes.concat([this.payload, this.receiverEI]);
             }
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             return super.serialize(ctx);
         }
         toLogEntry(ctx) {
@@ -1484,6 +1776,7 @@ let Security2CCNonceGet = (() => {
             const securityManager = assertSecurityTX(ctx, this.nodeId);
             this.ensureSequenceNumber(securityManager);
             this.payload = Bytes.from([this.sequenceNumber]);
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             return super.serialize(ctx);
         }
         toLogEntry(ctx) {
@@ -1560,6 +1853,7 @@ let Security2CCKEXReport = (() => {
                 encodeBitMask(this.supportedECDHProfiles, 7, ECDHProfiles.Curve25519),
                 encodeBitMask(this.requestedKeys, SecurityClass.S0_Legacy, SecurityClass.S2_Unauthenticated),
             ]);
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             return super.serialize(ctx);
         }
         toLogEntry(ctx) {
@@ -1687,6 +1981,7 @@ let Security2CCKEXSet = (() => {
                 encodeBitMask([this.selectedECDHProfile], 7, ECDHProfiles.Curve25519),
                 encodeBitMask(this.grantedKeys, SecurityClass.S0_Legacy, SecurityClass.S2_Unauthenticated),
             ]);
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             return super.serialize(ctx);
         }
         toLogEntry(ctx) {
@@ -1737,6 +2032,7 @@ let Security2CCKEXFail = (() => {
         failType;
         serialize(ctx) {
             this.payload = Bytes.from([this.failType]);
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             return super.serialize(ctx);
         }
         toLogEntry(ctx) {
@@ -1786,6 +2082,7 @@ let Security2CCPublicKeyReport = (() => {
                 Bytes.from([this.includingNode ? 1 : 0]),
                 this.publicKey,
             ]);
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             return super.serialize(ctx);
         }
         toLogEntry(ctx) {
@@ -1838,6 +2135,7 @@ let Security2CCNetworkKeyReport = (() => {
                 securityClassToBitMask(this.grantedKey),
                 this.networkKey,
             ]);
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             return super.serialize(ctx);
         }
         toLogEntry(ctx) {
@@ -1884,6 +2182,7 @@ let Security2CCNetworkKeyGet = (() => {
         requestedKey;
         serialize(ctx) {
             this.payload = securityClassToBitMask(this.requestedKey);
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             return super.serialize(ctx);
         }
         toLogEntry(ctx) {
@@ -1953,6 +2252,7 @@ let Security2CCTransferEnd = (() => {
             this.payload = Bytes.from([
                 (this.keyVerified ? 0b10 : 0) + (this.keyRequestComplete ? 0b1 : 0),
             ]);
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             return super.serialize(ctx);
         }
         toLogEntry(ctx) {
@@ -2002,6 +2302,7 @@ let Security2CCCommandsSupportedReport = (() => {
         supportedCCs;
         serialize(ctx) {
             this.payload = encodeCCList(this.supportedCCs, []);
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             return super.serialize(ctx);
         }
         toLogEntry(ctx) {