Merge pull request #24 from athombv/fix/encryption

Fix/encryption

Author: nozols

.gitignore

@@ -1,2 +1,3 @@
 /node_modules
-/dist
+/dist
+/private

package.json

@@ -18,7 +18,9 @@
     "prettier": "prettier . --write",
     "prettier:check": "prettier . --check",
     "tool:parse-telegram": "tsx ./tools/parse-telegram.ts",
-    "tool:update-test-telegrams": "tsx ./tools/update-test-telegrams.ts"
+    "tool:update-test-telegrams": "tsx ./tools/update-test-telegrams.ts",
+    "tool:decrypt-telegram": "tsx ./tools/decrypt-telegram.ts",
+    "tool:encrypt-telegram": "tsx ./tools/encrypt-telegram.ts"
   },
   "repository": {
     "type": "git",

src/index.ts

@@ -1,6 +1,7 @@
 import { DSMRParser } from './parsers/dsmr.js';
 import { getMbusDevice, MBUS_DEVICE_IDS } from './parsers/mbus.js';
 import { createDSMRStreamParser, createDSMRStreamTransformer } from './parsers/stream.js';
+import { ENCRYPTION_DEFAULT_AAD } from './util/encryption.js';
 import { DSMRFrameValid } from './util/frame-validation.js';
 
 export type DSMRParserOptions =
@@ -11,14 +12,17 @@ export type DSMRParserOptions =
       newLineChars?: '\r\n' | '\n';
       /** Enable the encryption detection mechanism. Enabled by default */
       decryptionKey?: never;
+      additionalAuthenticatedData?: never;
       encoding?: never;
     }
   | {
       /** Encrypted DSMR telegram */
       telegram: Buffer;
       /** Decryption key */
-      decryptionKey?: string;
-      /** Encoding of the data in the buffer, defaults to ascii */
+      decryptionKey?: Buffer;
+      /** AAD */
+      additionalAuthenticatedData?: Buffer;
+      /** Encoding of the data in the buffer, defaults to binary */
       encoding?: BufferEncoding;
       /** New line characters */
       newLineChars?: '\r\n' | '\n';
@@ -98,6 +102,8 @@ export type DSMRParserResult = {
     value: number;
     valid: boolean;
   };
+  /** Only set when encryption is used */
+  additionalAuthenticatedDataValid?: boolean;
 };
 
 export * from './util/errors.js';
@@ -109,4 +115,5 @@ export const DSMR = {
   isValidFrame: DSMRFrameValid,
   MBUS_DEVICE_IDS,
   getMbusDevice,
+  ENCRYPTION_DEFAULT_AAD,
 } as const;

src/parsers/dsmr.ts

@@ -46,17 +46,22 @@ export const DSMRParser = (options: DSMRParserOptions): DSMRParserResult => {
   options.newLineChars = options.newLineChars ?? '\r\n';
 
   let telegram: string;
+  let decryptError: Error | undefined;
 
   if (typeof options.telegram === 'string') {
     telegram = options.telegram;
-  } else if (typeof options.decryptionKey !== 'string') {
+  } else if (!Buffer.isBuffer(options.decryptionKey)) {
     telegram = options.telegram.toString(options.encoding ?? DEFAULT_FRAME_ENCODING);
   } else {
-    telegram = decryptFrame({
+    const { content, error } = decryptFrame({
       data: options.telegram,
       key: options.decryptionKey,
+      additionalAuthenticatedData: options.additionalAuthenticatedData,
       encoding: options.encoding ?? DEFAULT_FRAME_ENCODING,
     });
+
+    telegram = content;
+    decryptError = error;
   }
 
   const lines = telegram.split(options.newLineChars);
@@ -119,6 +124,12 @@ export const DSMRParser = (options: DSMRParserOptions): DSMRParserResult => {
   }
 
   if (objectsParsed === 0) {
+    // If we're unable to parse the data and we have a decryption error,
+    // the error is probably in the decryption.
+    if (decryptError) {
+      throw decryptError;
+    }
+
     throw new DSMRParserError('Invalid telegram. No COSEM objects found.');
   }
 

src/parsers/stream-encrypted.ts

@@ -99,35 +99,52 @@ export class EncryptedDSMRStreamParser implements DSMRStreamParser {
     // Wait for more data to decode the header
     if (!this.header) return;
 
-    const totalLength = this.header.contentLength + ENCRYPTED_DSMR_GCM_TAG_LEN;
+    const totalLength =
+      ENCRYPTED_DSMR_HEADER_LEN + this.header.contentLength + ENCRYPTED_DSMR_GCM_TAG_LEN;
 
     // Wait until full telegram is received
     if (this.telegram.length < totalLength) return;
 
     clearTimeout(this.fullFrameRequiredTimeout);
 
+    let decryptError: Error | undefined;
+
     try {
-      const content = this.telegram.subarray(ENCRYPTED_DSMR_HEADER_LEN, this.header.contentLength);
+      const encryptedContent = this.telegram.subarray(
+        ENCRYPTED_DSMR_HEADER_LEN,
+        ENCRYPTED_DSMR_HEADER_LEN + this.header.contentLength,
+      );
       const footer = decodeFooter(this.telegram, this.header);
-      const decrypted = decryptFrameContents({
-        data: content,
+
+      const { content, error } = decryptFrameContents({
+        data: encryptedContent,
         header: this.header,
         footer,
-        key: this.options.decryptionKey ?? '',
+        key: this.options.decryptionKey ?? Buffer.alloc(0),
+        additionalAuthenticatedData: this.options.additionalAuthenticatedData,
         encoding: this.options.encoding ?? DEFAULT_FRAME_ENCODING,
       });
+
+      decryptError = error;
+
       const result = DSMRParser({
-        telegram: decrypted,
+        telegram: content,
         newLineChars: this.options.newLineChars,
       });
 
+      result.additionalAuthenticatedDataValid = decryptError === undefined;
+
       this.options.callback(null, result);
     } catch (error) {
-      if (error instanceof DSMRError) {
-        error.withRawTelegram(this.telegram);
+      // If we had a decryption error that is the cause of the error.
+      // So that should be returned to the listener.
+      const realError = decryptError ?? error;
+
+      if (realError instanceof DSMRError) {
+        realError.withRawTelegram(this.telegram);
       }
 
-      this.options.callback(error, undefined);
+      this.options.callback(realError, undefined);
     }
 
     const remainingData = this.telegram.subarray(totalLength, this.telegram.length);

src/util/encryption.ts

@@ -5,16 +5,17 @@ import { DSMRDecodeError, DSMRDecryptionError } from './errors.js';
  * For now this is specific to the luxembourg's smart metering system. (E-Meter P1 Specification)
  * They wrap a DSMR telegram in a custom frame with the following format:
  *
- * | Byte   | Description         | Example                             |
- * | ------ | ------------------- | ----------------------------------- |
- * | 0      | SOF                 | DB (fixed)                          |
- * | 1      | System Title Length | 08 (fixed)                          |
- * | 2-9    | System Title        | 00 11 22 33 44 55 66 77             |
- * | 10-11  | Length of the frame | 00 11                               |
- * | 12     | SOF Frame Counter   | 30                                  |
- * | 13-16  | Frame Counter       | 00 11 22 33                         |
- * | 17-n   | Frame               | <Encrypted DSMR frame>              |
- * | n-n+12 | GCM Tag             | 00 11 22 33 44 55 66 77 88 99 AA BB |
+ * | Byte   | Description          | Example                             |
+ * | ------ | -------------------- | ----------------------------------- |
+ * | 0      | SOF                  | DB (fixed)                          |
+ * | 1      | System Title Length  | 08 (fixed)                          |
+ * | 2-9    | System Title         | 00 11 22 33 44 55 66 77             |
+ * | 10     | Content Length Start | 82 (fixed)                          |
+ * | 11-12  | Length of the frame  | 00 11                               |
+ * | 13     | SOF Frame Counter    | 30 (fixed)                          |
+ * | 14-17  | Frame Counter        | 00 11 22 33                         |
+ * | 18-n   | Frame                | <Encrypted DSMR frame>              |
+ * | n-n+12 | GCM Tag              | 00 11 22 33 44 55 66 77 88 99 AA BB |
  *
  * The encrypted DSMR frame is encrypted using AES-128-GCM, and the user can request the encryption
  * key from the utility company. The IV is the concatenation of the system title and the frame
@@ -24,10 +25,13 @@ import { DSMRDecodeError, DSMRDecryptionError } from './errors.js';
  * excluded.
  */
 
-export const ENCRYPTED_DSMR_TELEGRAM_SOF = 0xdb;
+export const ENCRYPTED_DSMR_TELEGRAM_SOF = 0xdb; // DLMS_COMMAND_GENERAL_GLO_CIPHERING
+export const ENCRYPTED_DSMR_CONTENT_LENGTH_START = 0x82; // DLMS type for uint16_t (Big Endian)
+export const ENCRYPTED_DSMR_SECURITY_TYPE = 0x30; // DLMS_SECURITY_AUTHENTICATION_ENCRYPTION
 export const ENCRYPTED_DSMR_SYSTEM_TITLE_LEN = 8;
 export const ENCRYPTED_DSMR_GCM_TAG_LEN = 12;
-export const ENCRYPTED_DSMR_HEADER_LEN = 17;
+export const ENCRYPTED_DSMR_HEADER_LEN = 18;
+export const ENCRYPTION_DEFAULT_AAD = Buffer.from('00112233445566778899aabbccddeeff', 'hex');
 
 /**
  * @param data A buffer that starts with the header (bytes 0-16) of the E-Meter P1 frame
@@ -40,29 +44,43 @@ export const decodeHeader = (data: Buffer) => {
 
   let index = 0;
 
-  if (data[index++] !== ENCRYPTED_DSMR_TELEGRAM_SOF) {
-    throw new DSMRDecodeError('Invalid telegram sof');
+  const sof = data[index++];
+  if (sof !== ENCRYPTED_DSMR_TELEGRAM_SOF) {
+    throw new DSMRDecodeError(`Invalid telegram sof 0x${sof.toString(16)}`);
   }
 
-  if (data[index++] !== ENCRYPTED_DSMR_SYSTEM_TITLE_LEN) {
-    throw new DSMRDecodeError('Invalid system title length');
+  const systemTitleLen = data[index++];
+  if (systemTitleLen !== ENCRYPTED_DSMR_SYSTEM_TITLE_LEN) {
+    throw new DSMRDecodeError(`Invalid system title length 0x${systemTitleLen.toString(16)}`);
   }
 
   const systemTitle = data.subarray(index, index + ENCRYPTED_DSMR_SYSTEM_TITLE_LEN);
   index += ENCRYPTED_DSMR_SYSTEM_TITLE_LEN;
-  const contentLength = data.readUInt16LE(index);
+
+  const contentLengthStart = data[index++];
+  if (contentLengthStart !== ENCRYPTED_DSMR_CONTENT_LENGTH_START) {
+    throw new DSMRDecodeError(
+      `Invalid content length start byte 0x${contentLengthStart.toString(16)}`,
+    );
+  }
+
+  // The entire header is 18 bytes long, but for some reason the content length uses 17 as
+  // length for the header. Maybe they don't include the SOF byte?
+  const contentLength = data.readUInt16BE(index) + 1 - ENCRYPTED_DSMR_HEADER_LEN;
   index += 2;
 
-  // According to the documentation, this should be 0x30, but it often is not.
-  const sofFrameCounter = data[index++];
+  const securityType = data[index++];
+  if (securityType !== ENCRYPTED_DSMR_SECURITY_TYPE) {
+    throw new DSMRDecodeError(`Invalid frame counter 0x${securityType.toString(16)}`);
+  }
 
   const frameCounter = data.subarray(index, index + 4);
   index += 4;
 
   return {
     systemTitle,
     frameCounter,
-    sofFrameCounter,
+    securityType,
     contentLength,
   };
 };
@@ -77,7 +95,10 @@ export const decodeFooter = (data: Buffer, header: ReturnType<typeof decodeHeade
   }
 
   return {
-    gcmTag: data.subarray(header.contentLength, header.contentLength + ENCRYPTED_DSMR_GCM_TAG_LEN),
+    gcmTag: data.subarray(
+      ENCRYPTED_DSMR_HEADER_LEN + header.contentLength,
+      ENCRYPTED_DSMR_HEADER_LEN + header.contentLength + ENCRYPTED_DSMR_GCM_TAG_LEN,
+    ),
   };
 };
 
@@ -88,6 +109,7 @@ export const decryptFrameContents = ({
   footer,
   key,
   encoding,
+  additionalAuthenticatedData,
 }: {
   /** The encrypted DSMR frame */
   data: Buffer;
@@ -96,42 +118,93 @@ export const decryptFrameContents = ({
   /** The decoded footer (use {@link decodeFooter}) */
   footer: ReturnType<typeof decodeFooter>;
   /** The encryption key */
-  key: string;
+  key: Buffer;
   encoding: BufferEncoding;
+  /** Optional additional authenticated data (AAD) to be used in the decryption. */
+  additionalAuthenticatedData?: Buffer;
 }) => {
-  if (data.length !== header.contentLength - ENCRYPTED_DSMR_HEADER_LEN) {
-    throw new Error(
-      `Invalid frame length got ${data.length} expected ${header.contentLength - ENCRYPTED_DSMR_HEADER_LEN}`,
-    );
+  if (data.length !== header.contentLength) {
+    throw new Error(`Invalid frame length got ${data.length} expected ${header.contentLength}`);
+  }
+
+  if (additionalAuthenticatedData?.length == 16) {
+    additionalAuthenticatedData = Buffer.concat([Buffer.from([0x30]), additionalAuthenticatedData]);
   }
 
   const iv = Buffer.concat([header.systemTitle, header.frameCounter]);
+  let cipher: crypto.DecipherGCM;
+  let content = '';
 
-  // Wrap in try-catch to throw a DSMRDecryptionError instead of a generic error.
+  // 1: decrypt the frame, this will only throw if the key, iv or AAD are not
+  // correct due to their format. `cipher.update` will never throw, but if the key/iv/aad
+  // are not valid it may return gibberish.
   try {
-    const cipher = crypto.createDecipheriv('aes-128-gcm', key, iv, {
+    cipher = crypto.createDecipheriv('aes-128-gcm', key, iv, {
       authTagLength: ENCRYPTED_DSMR_GCM_TAG_LEN,
     });
+    cipher.setAutoPadding(false);
     cipher.setAuthTag(footer.gcmTag);
 
-    return cipher.update(data, undefined, encoding) + cipher.final(encoding);
+    if (additionalAuthenticatedData) {
+      cipher.setAAD(additionalAuthenticatedData);
+    }
+
+    content += cipher.update(data, undefined, encoding);
   } catch (error) {
-    throw new DSMRDecryptionError(error);
+    return {
+      content,
+      error: new DSMRDecryptionError(error),
+    };
   }
+
+  // 2: call final on the frame. This will check the AAD/iv/key.
+  // When either of these are invalid, it will throw an "Unsupported state or unable to authenticate data" error.
+  // If the AAD is invalid, but the key/iv are valid the content can still be a valid DSMR frame!
+  try {
+    content += cipher.final(encoding);
+  } catch (error) {
+    return {
+      content,
+      error: new DSMRDecryptionError(error),
+    };
+  }
+
+  return {
+    content,
+  };
 };
 
 /** Decrypts a full encrypted DSMR frame */
 export const decryptFrame = ({
   data,
   key,
   encoding,
+  additionalAuthenticatedData,
 }: {
   data: Buffer;
-  key: string;
+  key: Buffer;
+  additionalAuthenticatedData?: Buffer;
   encoding: BufferEncoding;
 }) => {
   const header = decodeHeader(data);
   const footer = decodeFooter(data, header);
-  const content = data.subarray(ENCRYPTED_DSMR_HEADER_LEN, header.contentLength);
-  return decryptFrameContents({ data: content, header, footer, key, encoding });
+  const encryptedContent = data.subarray(
+    ENCRYPTED_DSMR_HEADER_LEN,
+    ENCRYPTED_DSMR_HEADER_LEN + header.contentLength,
+  );
+  const { content, error } = decryptFrameContents({
+    data: encryptedContent,
+    header,
+    footer,
+    key,
+    additionalAuthenticatedData,
+    encoding,
+  });
+
+  return {
+    header,
+    footer,
+    content,
+    error,
+  };
 };