@zwave-js/cc 14.1.0 → 14.3.0

package/build/esm/cc/Security2CC.js

@@ -32,7 +32,7 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
     }
     return useValue ? value : void 0;
 };
-import { CommandClasses, MPANState, MessagePriority, SECURITY_S2_AUTH_TAG_LENGTH, SPANState, SecurityClass, TransmitOptions, ZWaveError, ZWaveErrorCodes, decryptAES128CCM, encodeBitMask, encryptAES128CCM, getCCName, highResTimestamp, isLongRangeNodeId, isTransmissionError, isZWaveError, parseBitMask, parseCCList, securityClassIsS2, securityClassOrder, validatePayload, } from "@zwave-js/core";
+import { CommandClasses, MPANState, MessagePriority, SPANState, SecurityClass, TransmitOptions, ZWaveError, ZWaveErrorCodes, decryptAES128CCMAsync, decryptAES128CCMSync, encodeBitMask, encryptAES128CCMAsync, encryptAES128CCMSync, getCCName, highResTimestamp, isLongRangeNodeId, isTransmissionError, isZWaveError, parseBitMask, parseCCList, securityClassIsS2, securityClassOrder, validatePayload, } from "@zwave-js/core";
 import { EncapsulationFlags, NODE_ID_BROADCAST, NODE_ID_BROADCAST_LR, encodeCCList, } from "@zwave-js/core/safe";
 import { Bytes } from "@zwave-js/shared/safe";
 import { buffer2hex, getEnumMemberName, pick } from "@zwave-js/shared/safe";
@@ -56,6 +56,7 @@ function bitMaskToSecurityClass(buffer, offset) {
     validatePayload(keys.length === 1);
     return keys[0];
 }
+const SECURITY_S2_AUTH_TAG_LENGTH = 8;
 function getAuthenticationData(sendingNodeId, destination, homeId, commandLength, unencryptedPayload) {
     const nodeIdSize = isLongRangeNodeId(sendingNodeId) || isLongRangeNodeId(destination)
         ? 2
@@ -110,17 +111,20 @@ function assertSecurityTX(ctx, destination) {
     }
     return ret;
 }
-function decryptSinglecast(ctx, securityManager, sendingNodeId, curSequenceNumber, prevSequenceNumber, ciphertext, authData, authTag, spanState, extensions) {
+/** @deprecated Use {@link decryptSinglecastAsync} instead */
+function decryptSinglecastSync(ctx, securityManager, sendingNodeId, curSequenceNumber, prevSequenceNumber, ciphertext, authData, authTag, spanState, extensions) {
     const decryptWithNonce = (nonce) => {
         const { keyCCM: key } = securityManager.getKeysForNode(sendingNodeId);
         const iv = nonce;
         return {
             key,
             iv,
-            ...decryptAES128CCM(key, iv, ciphertext, authData, authTag),
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
+            ...decryptAES128CCMSync(key, iv, ciphertext, authData, authTag),
         };
     };
     const getNonceAndDecrypt = () => {
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
         const iv = securityManager.nextNonce(sendingNodeId);
         return decryptWithNonce(iv);
     };
@@ -172,6 +176,7 @@ function decryptSinglecast(ctx, securityManager, sendingNodeId, curSequenceNumbe
         const isBootstrappingNode = securityManager.tempKeys.has(sendingNodeId);
         if (isBootstrappingNode) {
             // We're currently bootstrapping the node, it might be using a temporary key
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             securityManager.initializeTempSPAN(sendingNodeId, senderEI, receiverEI);
             const ret = getNonceAndDecrypt();
             // Decryption with the temporary key worked
@@ -203,6 +208,7 @@ function decryptSinglecast(ctx, securityManager, sendingNodeId, curSequenceNumbe
                 continue;
             }
             // Initialize an SPAN with that security class
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             securityManager.initializeSPAN(sendingNodeId, secClass, senderEI, receiverEI);
             const ret = getNonceAndDecrypt();
             // It worked, return the result
@@ -230,17 +236,212 @@ function decryptSinglecast(ctx, securityManager, sendingNodeId, curSequenceNumbe
         securityClass: undefined,
     };
 }
-function decryptMulticast(sendingNodeId, securityManager, groupId, ciphertext, authData, authTag) {
+async function decryptSinglecastAsync(ctx, securityManager, sendingNodeId, curSequenceNumber, prevSequenceNumber, ciphertext, authData, authTag, spanState, extensions) {
+    const decryptWithNonce = async (nonce) => {
+        const { keyCCM: key } = securityManager.getKeysForNode(sendingNodeId);
+        const iv = nonce;
+        return {
+            key,
+            iv,
+            ...(await decryptAES128CCMAsync(ciphertext, key, iv, authData, authTag)),
+        };
+    };
+    const getNonceAndDecrypt = async () => {
+        const iv = await securityManager.nextNonceAsync(sendingNodeId);
+        return decryptWithNonce(iv);
+    };
+    if (spanState.type === SPANState.SPAN) {
+        // There SHOULD be a shared SPAN between both parties. But experience has shown that both could have
+        // sent a command at roughly the same time, using the same SPAN for encryption.
+        // To avoid a nasty desync and both nodes trying to resync at the same time, causing message loss,
+        // we accept commands encrypted with the previous SPAN under very specific circumstances:
+        if (
+        // The previous SPAN is still known, i.e. the node didn't send another command that was successfully decrypted
+        !!spanState.currentSPAN
+            // it is still valid
+            && spanState.currentSPAN.expires > highResTimestamp()
+            // The received command is exactly the next, expected one
+            && prevSequenceNumber != undefined
+            && curSequenceNumber === ((prevSequenceNumber + 1) & 0xff)
+            // And in case of a mock-based test, do this only on the controller
+            && !ctx.__internalIsMockNode) {
+            const nonce = spanState.currentSPAN.nonce;
+            spanState.currentSPAN = undefined;
+            // If we could decrypt this way, we're done...
+            const result = await decryptWithNonce(nonce);
+            if (result.authOK) {
+                return {
+                    ...result,
+                    securityClass: spanState.securityClass,
+                };
+            }
+            // ...otherwise, we need to try the normal way
+        }
+        else {
+            // forgetting the current SPAN shouldn't be necessary but better be safe than sorry
+            spanState.currentSPAN = undefined;
+        }
+        // This can only happen if the security class is known
+        return {
+            ...(await getNonceAndDecrypt()),
+            securityClass: spanState.securityClass,
+        };
+    }
+    else if (spanState.type === SPANState.LocalEI) {
+        // We've sent the other our receiver's EI and received its sender's EI,
+        // meaning we can now establish an SPAN
+        const senderEI = getSenderEI(extensions);
+        if (!senderEI)
+            failNoSPAN();
+        const receiverEI = spanState.receiverEI;
+        // How we do this depends on whether we know the security class of the other node
+        const isBootstrappingNode = securityManager.tempKeys.has(sendingNodeId);
+        if (isBootstrappingNode) {
+            // We're currently bootstrapping the node, it might be using a temporary key
+            await securityManager.initializeTempSPANAsync(sendingNodeId, senderEI, receiverEI);
+            const ret = await getNonceAndDecrypt();
+            // Decryption with the temporary key worked
+            if (ret.authOK) {
+                return {
+                    ...ret,
+                    securityClass: SecurityClass.Temporary,
+                };
+            }
+            // Reset the SPAN state and try with the recently granted security class
+            securityManager.setSPANState(sendingNodeId, spanState);
+        }
+        // When ending up here, one of two situations has occured:
+        // a) We've taken over an existing network and do not know the node's security class
+        // b) We know the security class, but we're about to establish a new SPAN. This may happen at a lower
+        //    security class than the one the node normally uses, e.g. when we're being queried for securely
+        //    supported CCs.
+        // In both cases, we should simply try decoding with multiple security classes, starting from the highest one.
+        // If this fails, we restore the previous (partial) SPAN state.
+        // Try all security classes where we do not definitely know that it was not granted
+        // While bootstrapping a node, we consider the key that is being exchanged (including S0) to be the highest. No need to look at others
+        const possibleSecurityClasses = isBootstrappingNode
+            ? [ctx.getHighestSecurityClass(sendingNodeId)]
+            : securityClassOrder.filter((s) => ctx.hasSecurityClass(sendingNodeId, s)
+                !== false);
+        for (const secClass of possibleSecurityClasses) {
+            // Skip security classes we don't have keys for
+            if (!securityManager.hasKeysForSecurityClass(secClass)) {
+                continue;
+            }
+            // Initialize an SPAN with that security class
+            await securityManager.initializeSPANAsync(sendingNodeId, secClass, senderEI, receiverEI);
+            const ret = await getNonceAndDecrypt();
+            // It worked, return the result
+            if (ret.authOK) {
+                // Also if we weren't sure before, we now know that the security class is granted
+                if (ctx.hasSecurityClass(sendingNodeId, secClass)
+                    === undefined) {
+                    ctx.setSecurityClass(sendingNodeId, secClass, true);
+                }
+                return {
+                    ...ret,
+                    securityClass: secClass,
+                };
+            }
+            else {
+                // Reset the SPAN state and try with the next security class
+                securityManager.setSPANState(sendingNodeId, spanState);
+            }
+        }
+    }
+    // Nothing worked, fail the decryption
+    return {
+        plaintext: new Uint8Array(),
+        authOK: false,
+        securityClass: undefined,
+    };
+}
+/** @deprecated Use {@link decryptMulticastAsync} instead */
+function decryptMulticastSync(sendingNodeId, securityManager, groupId, ciphertext, authData, authTag) {
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     const iv = securityManager.nextPeerMPAN(sendingNodeId, groupId);
     const { keyCCM: key } = securityManager.getKeysForNode(sendingNodeId);
     return {
         key,
         iv,
-        ...decryptAES128CCM(key, iv, ciphertext, authData, authTag),
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
+        ...decryptAES128CCMSync(key, iv, ciphertext, authData, authTag),
         // The security class is irrelevant when decrypting multicast commands
         securityClass: undefined,
     };
 }
+async function decryptMulticastAsync(sendingNodeId, securityManager, groupId, ciphertext, authData, authTag) {
+    const iv = await securityManager.nextPeerMPANAsync(sendingNodeId, groupId);
+    const { keyCCM: key } = securityManager.getKeysForNode(sendingNodeId);
+    return {
+        key,
+        iv,
+        ...(await decryptAES128CCMAsync(ciphertext, key, iv, authData, authTag)),
+        // The security class is irrelevant when decrypting multicast commands
+        securityClass: undefined,
+    };
+}
+function parseExtensions(buffer, wasEncrypted) {
+    const extensions = [];
+    let mustDiscardCommand = false;
+    let offset = 0;
+    parsing: while (true) {
+        if (buffer.length < offset + 2) {
+            // An S2 extension was expected, but the buffer is too short
+            mustDiscardCommand = true;
+            break parsing;
+        }
+        // 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;
+            break parsing;
+        }
+        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;
+            break parsing;
+        }
+        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 parsing;
+    }
+    return {
+        extensions,
+        mustDiscardCommand,
+        bytesRead: offset,
+    };
+}
 function getDestinationIDTX() {
     if (this.isSinglecast())
         return this.nodeId;
@@ -302,7 +503,7 @@ let Security2CCAPI = (() => {
             if (!securityManager) {
                 throw new ZWaveError(`Nonces can only be sent if secure communication is set up!`, ZWaveErrorCodes.Driver_NoSecurity);
             }
-            const receiverEI = securityManager.generateNonce(this.endpoint.nodeId);
+            const receiverEI = await securityManager.generateNonceAsync(this.endpoint.nodeId);
             const cc = new Security2CCNonceReport({
                 nodeId: this.endpoint.nodeId,
                 endpointIndex: this.endpoint.index,
@@ -922,6 +1123,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);
@@ -934,61 +1136,12 @@ let Security2CCMessageEncapsulation = (() => {
             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);
+            if (hasExtensions) {
+                const parseResult = parseExtensions(raw.payload.subarray(offset), false);
+                extensions.push(...parseResult.extensions);
+                offset += parseResult.bytesRead;
+                mustDiscardCommand = parseResult.mustDiscardCommand;
+            }
             const mcctx = (() => {
                 const multicastGroupId = getMulticastGroupId(extensions);
                 if (ctx.frameType === "multicast" || ctx.frameType === "broadcast") {
@@ -1008,9 +1161,11 @@ let Security2CCMessageEncapsulation = (() => {
             // we still need to increment the SPAN or MPAN state
             if (mustDiscardCommand) {
                 if (mcctx.isMulticast) {
+                    // eslint-disable-next-line @typescript-eslint/no-deprecated
                     securityManager.nextPeerMPAN(ctx.sourceNodeId, mcctx.groupId);
                 }
                 else {
+                    // eslint-disable-next-line @typescript-eslint/no-deprecated
                     securityManager.nextNonce(ctx.sourceNodeId);
                 }
                 validatePayload.fail("Invalid S2 extension");
@@ -1043,7 +1198,9 @@ let Security2CCMessageEncapsulation = (() => {
                     securityManager.storePeerMPAN(ctx.sourceNodeId, mcctx.groupId, { type: MPANState.OutOfSync });
                     failNoMPAN();
                 }
-                decrypt = () => decryptMulticast(ctx.sourceNodeId, securityManager, mcctx.groupId, ciphertext, authData, authTag);
+                decrypt = () => 
+                // eslint-disable-next-line @typescript-eslint/no-deprecated
+                decryptMulticastSync(ctx.sourceNodeId, securityManager, mcctx.groupId, ciphertext, authData, authTag);
             }
             else {
                 // Decrypt payload and verify integrity
@@ -1057,7 +1214,9 @@ let Security2CCMessageEncapsulation = (() => {
                     // 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);
+                decrypt = () => 
+                // eslint-disable-next-line @typescript-eslint/no-deprecated
+                decryptSinglecastSync(ctx, securityManager, ctx.sourceNodeId, sequenceNumber, prevSequenceNumber, ciphertext, authData, authTag, spanState, extensions);
             }
             let plaintext;
             let authOK = false;
@@ -1108,8 +1267,12 @@ let Security2CCMessageEncapsulation = (() => {
             // 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);
+            if (hasEncryptedExtensions) {
+                const parseResult = parseExtensions(plaintext, true);
+                extensions.push(...parseResult.extensions);
+                offset += parseResult.bytesRead;
+                mustDiscardCommand = parseResult.mustDiscardCommand;
+            }
             // Before we can continue, check if the command must be discarded
             if (mustDiscardCommand) {
                 validatePayload.fail("Invalid extension");
@@ -1131,6 +1294,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 +1312,187 @@ 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;
+            if (hasExtensions) {
+                const parseResult = parseExtensions(raw.payload.subarray(offset), false);
+                extensions.push(...parseResult.extensions);
+                offset += parseResult.bytesRead;
+                mustDiscardCommand = parseResult.mustDiscardCommand;
+            }
+            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) {
+                    await securityManager.nextPeerMPANAsync(ctx.sourceNodeId, mcctx.groupId);
+                }
+                else {
+                    await securityManager.nextNonceAsync(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 = () => decryptMulticastAsync(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 = () => decryptSinglecastAsync(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,
+                } = await 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) {
+                const parseResult = parseExtensions(plaintext, true);
+                extensions.push(...parseResult.extensions);
+                offset += parseResult.bytesRead;
+                mustDiscardCommand = parseResult.mustDiscardCommand;
+            }
+            // 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;
@@ -1187,7 +1532,8 @@ let Security2CCMessageEncapsulation = (() => {
         getMulticastGroupId() {
             return getMulticastGroupId(this.extensions);
         }
-        maybeAddSPANExtension(ctx, securityManager) {
+        /** @deprecated Use {@link maybeAddSPANExtensionAsync} instead */
+        maybeAddSPANExtensionSync(ctx, securityManager) {
             if (!this.isSinglecast())
                 return;
             const receiverNodeId = this.nodeId;
@@ -1200,12 +1546,14 @@ let Security2CCMessageEncapsulation = (() => {
             else if (spanState.type === SPANState.RemoteEI) {
                 // We have the receiver's EI, generate our input and send it over
                 // With both, we can create an SPAN
+                // eslint-disable-next-line @typescript-eslint/no-deprecated
                 const senderEI = securityManager.generateNonce(undefined);
                 const receiverEI = spanState.receiverEI;
                 // While bootstrapping a node, prefer the temporary key, unless the
                 // specific command specifies a security class
                 if (this.securityClass == undefined
                     && securityManager.tempKeys.has(receiverNodeId)) {
+                    // eslint-disable-next-line @typescript-eslint/no-deprecated
                     securityManager.initializeTempSPAN(receiverNodeId, senderEI, receiverEI);
                 }
                 else {
@@ -1214,6 +1562,7 @@ let Security2CCMessageEncapsulation = (() => {
                     if (securityClass == undefined) {
                         throw new ZWaveError("No security class defined for this command!", ZWaveErrorCodes.Security2CC_NoSPAN);
                     }
+                    // eslint-disable-next-line @typescript-eslint/no-deprecated
                     securityManager.initializeSPAN(receiverNodeId, securityClass, senderEI, receiverEI);
                 }
                 // Add or update the SPAN extension
@@ -1227,11 +1576,53 @@ let Security2CCMessageEncapsulation = (() => {
                 }
             }
         }
+        async maybeAddSPANExtensionAsync(ctx, securityManager) {
+            if (!this.isSinglecast())
+                return;
+            const receiverNodeId = this.nodeId;
+            const spanState = securityManager.getSPANState(receiverNodeId);
+            if (spanState.type === SPANState.None
+                || spanState.type === SPANState.LocalEI) {
+                // Can't do anything here if we don't have the receiver's EI
+                throw new ZWaveError(`Security S2 CC requires the receiver's nonce to be sent!`, ZWaveErrorCodes.Security2CC_NoSPAN);
+            }
+            else if (spanState.type === SPANState.RemoteEI) {
+                // We have the receiver's EI, generate our input and send it over
+                // With both, we can create an SPAN
+                const senderEI = await securityManager.generateNonceAsync(undefined);
+                const receiverEI = spanState.receiverEI;
+                // While bootstrapping a node, prefer the temporary key, unless the
+                // specific command specifies a security class
+                if (this.securityClass == undefined
+                    && securityManager.tempKeys.has(receiverNodeId)) {
+                    await securityManager.initializeTempSPANAsync(receiverNodeId, senderEI, receiverEI);
+                }
+                else {
+                    const securityClass = this.securityClass
+                        ?? ctx.getHighestSecurityClass(receiverNodeId);
+                    if (securityClass == undefined) {
+                        throw new ZWaveError("No security class defined for this command!", ZWaveErrorCodes.Security2CC_NoSPAN);
+                    }
+                    await securityManager.initializeSPANAsync(receiverNodeId, securityClass, senderEI, receiverEI);
+                }
+                // Add or update the SPAN extension
+                let spanExtension = this.extensions.find((e) => e instanceof SPANExtension);
+                if (spanExtension) {
+                    spanExtension.senderEI = senderEI;
+                }
+                else {
+                    spanExtension = new SPANExtension({ senderEI });
+                    this.extensions.push(spanExtension);
+                }
+            }
+        }
+        /** @deprecated Use {@link serializeAsync} instead */
         serialize(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);
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
+            this.maybeAddSPANExtensionSync(ctx, securityManager);
             const unencryptedExtensions = this.extensions.filter((e) => !e.isEncrypted());
             const encryptedExtensions = this.extensions.filter((e) => e.isEncrypted());
             const unencryptedPayload = Bytes.concat([
@@ -1242,6 +1633,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([
@@ -1259,6 +1651,7 @@ let Security2CCMessageEncapsulation = (() => {
                 // Singlecast:
                 // Generate a nonce for encryption, and remember it to attempt decryption
                 // of potential in-flight messages from the target node.
+                // eslint-disable-next-line @typescript-eslint/no-deprecated
                 iv = securityManager.nextNonce(this.nodeId, true);
                 const { keyCCM } = 
                 // Prefer the overridden security class if it was given
@@ -1269,11 +1662,13 @@ let Security2CCMessageEncapsulation = (() => {
             }
             else {
                 // Multicast:
+                // eslint-disable-next-line @typescript-eslint/no-deprecated
                 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);
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
+            const { ciphertext: ciphertextPayload, authTag } = encryptAES128CCMSync(key, iv, plaintextPayload, authData, SECURITY_S2_AUTH_TAG_LENGTH);
             // Remember key and IV for debugging purposes
             this.key = key;
             this.iv = iv;
@@ -1285,8 +1680,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
+            await this.maybeAddSPANExtensionAsync(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 = await securityManager.nextNonceAsync(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 = await securityManager.getMulticastKeyAndIVAsync(destinationTag);
+                key = keyAndIV.key;
+                iv = keyAndIV.iv;
+            }
+            const { ciphertext: ciphertextPayload, authTag } = await encryptAES128CCMAsync(plaintextPayload, key, iv, 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 +1878,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 +1941,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 +2018,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 +2146,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 +2197,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 +2247,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 +2300,7 @@ let Security2CCNetworkKeyReport = (() => {
                 securityClassToBitMask(this.grantedKey),
                 this.networkKey,
             ]);
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             return super.serialize(ctx);
         }
         toLogEntry(ctx) {
@@ -1884,6 +2347,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 +2417,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 +2467,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) {