@chainlesschain/personal-data-hub 0.3.9 → 0.4.0

package/lib/mobile-extractor/bplist.js

@@ -0,0 +1,233 @@
+/**
+ * Minimal binary property list (bplist00) reader — enough to decode the
+ * NSKeyedArchiver blob stored in Manifest.db's `Files.file` column of an
+ * iOS backup, from which we pull each file's ProtectionClass +
+ * EncryptionKey + Size.
+ *
+ * Supports the object types that appear in those archives: null/bool,
+ * int, real, date, data, ASCII/UTF-16 string, UID, array, dict. This is
+ * NOT a general-purpose plist library — it targets the iOS-backup subset.
+ *
+ * Format reference: Apple CoreFoundation CFBinaryPList.c.
+ */
+
+"use strict";
+
+const BPLIST_MAGIC = "bplist00";
+
+class UID {
+  constructor(value) { this.UID = value; }
+}
+
+/**
+ * Parse a bplist00 buffer into a JS value. UIDs become {UID:n} (UID class
+ * instances); data stays a Buffer; dates become Date.
+ *
+ * @param {Buffer} buf
+ * @returns {*}
+ */
+function parseBplist(buf) {
+  if (!Buffer.isBuffer(buf) || buf.length < 32 + 8) {
+    throw new Error("parseBplist: buffer too small");
+  }
+  if (buf.toString("ascii", 0, 8) !== BPLIST_MAGIC) {
+    throw new Error("parseBplist: bad magic (not bplist00)");
+  }
+
+  // Trailer: last 32 bytes.
+  const trailer = buf.subarray(buf.length - 32);
+  const offsetSize = trailer.readUInt8(6);
+  const objectRefSize = trailer.readUInt8(7);
+  const numObjects = readUIntBE(trailer, 8, 8);
+  const topObject = readUIntBE(trailer, 16, 8);
+  const offsetTableOffset = readUIntBE(trailer, 24, 8);
+
+  // Offset table.
+  const offsets = [];
+  for (let i = 0; i < numObjects; i++) {
+    offsets.push(readUIntBE(buf, offsetTableOffset + i * offsetSize, offsetSize));
+  }
+
+  const cache = new Array(numObjects);
+
+  function readObject(index) {
+    if (index < 0 || index >= numObjects) throw new Error(`parseBplist: object ref ${index} out of range`);
+    if (cache[index] !== undefined) return cache[index];
+    let pos = offsets[index];
+    const marker = buf.readUInt8(pos);
+    const hi = marker >> 4;
+    const lo = marker & 0x0f;
+    pos += 1;
+    let result;
+
+    switch (hi) {
+      case 0x0: // singleton
+        if (lo === 0x0) result = null;
+        else if (lo === 0x8) result = false;
+        else if (lo === 0x9) result = true;
+        else result = null;
+        break;
+      case 0x1: { // int (2^lo bytes)
+        const n = 1 << lo;
+        result = readIntBE(buf, pos, n);
+        break;
+      }
+      case 0x2: { // real
+        const n = 1 << lo;
+        result = n === 4 ? buf.readFloatBE(pos) : buf.readDoubleBE(pos);
+        break;
+      }
+      case 0x3: { // date (8-byte double, seconds since 2001-01-01)
+        const secs = buf.readDoubleBE(pos);
+        result = new Date(Date.UTC(2001, 0, 1) + secs * 1000);
+        break;
+      }
+      case 0x4: { // data
+        const { count, dataPos } = readCount(buf, lo, pos);
+        result = Buffer.from(buf.subarray(dataPos, dataPos + count));
+        break;
+      }
+      case 0x5: { // ASCII string
+        const { count, dataPos } = readCount(buf, lo, pos);
+        result = buf.toString("ascii", dataPos, dataPos + count);
+        break;
+      }
+      case 0x6: { // UTF-16BE string
+        const { count, dataPos } = readCount(buf, lo, pos);
+        result = buf.toString("utf16le", dataPos, dataPos + count * 2);
+        // Stored big-endian; swap.
+        result = swapUtf16(buf.subarray(dataPos, dataPos + count * 2));
+        break;
+      }
+      case 0x8: { // UID
+        const n = lo + 1;
+        result = new UID(readUIntBE(buf, pos, n));
+        break;
+      }
+      case 0xa: { // array
+        const { count, dataPos } = readCount(buf, lo, pos);
+        const arr = [];
+        cache[index] = arr; // set before recursing (cycle-safe)
+        for (let i = 0; i < count; i++) {
+          const ref = readUIntBE(buf, dataPos + i * objectRefSize, objectRefSize);
+          arr.push(readObject(ref));
+        }
+        return arr;
+      }
+      case 0xd: { // dict
+        const { count, dataPos } = readCount(buf, lo, pos);
+        const dict = {};
+        cache[index] = dict;
+        const keysBase = dataPos;
+        const valsBase = dataPos + count * objectRefSize;
+        for (let i = 0; i < count; i++) {
+          const kRef = readUIntBE(buf, keysBase + i * objectRefSize, objectRefSize);
+          const vRef = readUIntBE(buf, valsBase + i * objectRefSize, objectRefSize);
+          const key = readObject(kRef);
+          dict[String(key)] = readObject(vRef);
+        }
+        return dict;
+      }
+      default:
+        throw new Error(`parseBplist: unknown object marker 0x${marker.toString(16)} at ${offsets[index]}`);
+    }
+    cache[index] = result;
+    return result;
+  }
+
+  return readObject(topObject);
+}
+
+// For collection/data/string markers, lo==0xf means the count follows as
+// a separate int object.
+function readCount(buf, lo, pos) {
+  if (lo !== 0x0f) return { count: lo, dataPos: pos };
+  const sizeMarker = buf.readUInt8(pos);
+  const n = 1 << (sizeMarker & 0x0f);
+  const count = readUIntBE(buf, pos + 1, n);
+  return { count, dataPos: pos + 1 + n };
+}
+
+function readUIntBE(buf, off, len) {
+  let n = 0;
+  for (let i = 0; i < len; i++) n = n * 256 + buf.readUInt8(off + i);
+  return n;
+}
+
+function readIntBE(buf, off, len) {
+  // bplist ints are unsigned for 1/2/4 bytes; 8-byte ints can be signed.
+  if (len <= 4) return readUIntBE(buf, off, len);
+  return Number(buf.readBigInt64BE(off));
+}
+
+function swapUtf16(beBuf) {
+  const swapped = Buffer.from(beBuf);
+  swapped.swap16();
+  return swapped.toString("utf16le");
+}
+
+/**
+ * Resolve an NSKeyedArchiver-shaped parsed plist into a plain object by
+ * following $top.root through the $objects table and replacing UID refs.
+ *
+ * @param {object} parsed — output of parseBplist on an NSKeyedArchiver blob
+ * @returns {*}
+ */
+function unwrapNSKeyedArchiver(parsed) {
+  if (!parsed || !Array.isArray(parsed.$objects) || !parsed.$top) {
+    throw new Error("unwrapNSKeyedArchiver: not an NSKeyedArchiver plist");
+  }
+  const objects = parsed.$objects;
+  const seen = new Map();
+
+  function resolve(node) {
+    if (node instanceof UID) {
+      if (seen.has(node.UID)) return seen.get(node.UID);
+      const target = objects[node.UID];
+      const out = resolveValue(target, node.UID);
+      return out;
+    }
+    return resolveValue(node, null);
+  }
+
+  function resolveValue(node, selfUid) {
+    if (node === "$null") return null;
+    if (node instanceof UID) return resolve(node);
+    if (Buffer.isBuffer(node) || node instanceof Date) return node;
+    if (Array.isArray(node)) {
+      const arr = [];
+      if (selfUid != null) seen.set(selfUid, arr);
+      for (const el of node) arr.push(resolve(el));
+      return arr;
+    }
+    if (node && typeof node === "object") {
+      // NSDictionary/NSArray encoded form has NS.keys / NS.objects.
+      if (Array.isArray(node["NS.keys"]) && Array.isArray(node["NS.objects"])) {
+        const d = {};
+        if (selfUid != null) seen.set(selfUid, d);
+        node["NS.keys"].forEach((k, i) => {
+          d[String(resolve(k))] = resolve(node["NS.objects"][i]);
+        });
+        return d;
+      }
+      if (Array.isArray(node["NS.objects"])) {
+        const arr = [];
+        if (selfUid != null) seen.set(selfUid, arr);
+        node["NS.objects"].forEach((v) => arr.push(resolve(v)));
+        return arr;
+      }
+      const out = {};
+      if (selfUid != null) seen.set(selfUid, out);
+      for (const [k, v] of Object.entries(node)) {
+        if (k === "$class") continue;
+        out[k] = resolve(v);
+      }
+      return out;
+    }
+    return node;
+  }
+
+  return resolve(parsed.$top.root != null ? parsed.$top.root : parsed.$top);
+}
+
+module.exports = { parseBplist, unwrapNSKeyedArchiver, UID, BPLIST_MAGIC };

package/lib/mobile-extractor/ios-backup-crypto.js

@@ -0,0 +1,315 @@
+/**
+ * Phase 7.5b — iOS encrypted iTunes backup cryptography.
+ *
+ * Implements the well-documented iOS backup keybag format so an encrypted
+ * backup (Manifest.plist → IsEncrypted=true) can be decrypted with the
+ * user's backup password. Pieces:
+ *
+ *   1. parseKeybag()        — TLV parser for the BackupKeyBag blob
+ *   2. deriveBackupKey()    — password → key (single or double PBKDF2,
+ *                             the latter for iOS 10.2+ DPSL/DPIC keybags)
+ *   3. aesUnwrap/aesWrap()  — RFC 3394 AES key wrap/unwrap (KAT-verified)
+ *   4. unwrapClassKeys()    — unwrap each passcode-protected class key
+ *   5. unwrapEncryptionKey()— 4-byte-class + wrapped-key blob → file key
+ *   6. decryptCBC()         — AES-256-CBC (zero IV) + truncate to size
+ *
+ * Every primitive is independently testable: aesUnwrap is checked against
+ * the official RFC 3394 test vectors, and the higher-level flow is checked
+ * with synthetic fixtures generated by the matching aesWrap + AES-CBC
+ * encrypt path. Byte-for-byte parity with a *real* Apple backup remains a
+ * device-E2E follow-up (no real encrypted backup available on Windows).
+ *
+ * References: iphone-dataprotection, mvt (mvt-project), iOSbackup (py).
+ */
+
+"use strict";
+
+const crypto = require("node:crypto");
+
+// RFC 3394 default initial value for AES key wrap.
+const RFC3394_IV = Buffer.from("A6A6A6A6A6A6A6A6", "hex");
+
+// WRAP flag bit: class key is wrapped with the passcode-derived key.
+const WRAP_PASSCODE = 2;
+
+// Tags that belong to an individual class-key block (vs. keybag header).
+const CLASSKEY_TAGS = new Set(["CLAS", "WRAP", "WPKY", "KTYP", "PBKY"]);
+// CLAS / KTYP / WRAP decode as big-endian integers; the rest stay raw.
+const INT_TAGS = new Set(["CLAS", "WRAP", "KTYP"]);
+
+/**
+ * Parse the BackupKeyBag TLV blob.
+ *
+ * Layout: repeated (4-byte ASCII tag)(4-byte big-endian length)(value).
+ * The header carries SALT/ITER/DPSL/DPIC/WRAP/UUID; each subsequent
+ * `UUID` tag opens a new class-key block (CLAS/WRAP/WPKY/KTYP).
+ *
+ * @param {Buffer} buf
+ * @returns {{attrs:object, classKeys:Object<number,object>}}
+ */
+function parseKeybag(buf) {
+  if (!Buffer.isBuffer(buf) || buf.length < 8) {
+    throw new Error("parseKeybag: keybag blob too short");
+  }
+  const attrs = {};
+  const classKeys = {};
+  let current = null;
+  let seenHeaderUuid = false;
+  let off = 0;
+
+  while (off + 8 <= buf.length) {
+    const tag = buf.toString("ascii", off, off + 4);
+    const len = buf.readUInt32BE(off + 4);
+    const valStart = off + 8;
+    const valEnd = valStart + len;
+    if (valEnd > buf.length) {
+      throw new Error(`parseKeybag: truncated value for tag ${tag}`);
+    }
+    const val = buf.subarray(valStart, valEnd);
+    off = valEnd;
+
+    if (tag === "UUID") {
+      if (!seenHeaderUuid) {
+        seenHeaderUuid = true;
+        attrs.UUID = Buffer.from(val);
+      } else {
+        // New class-key block.
+        if (current && current.CLAS !== undefined) classKeys[current.CLAS] = current;
+        current = { UUID: Buffer.from(val) };
+      }
+      continue;
+    }
+
+    if (current && CLASSKEY_TAGS.has(tag)) {
+      current[tag] = INT_TAGS.has(tag) ? readBeInt(val) : Buffer.from(val);
+      continue;
+    }
+
+    // Header attribute.
+    attrs[tag] = INT_TAGS.has(tag) || tag === "ITER" || tag === "DPIC" || tag === "VERS" || tag === "TYPE"
+      ? readBeInt(val)
+      : Buffer.from(val);
+  }
+  if (current && current.CLAS !== undefined) classKeys[current.CLAS] = current;
+
+  return { attrs, classKeys };
+}
+
+function readBeInt(buf) {
+  let n = 0;
+  for (const b of buf) n = n * 256 + b;
+  return n;
+}
+
+/**
+ * Derive the backup key from the password + keybag header.
+ *
+ * iOS 10.2+ keybags carry DPSL (salt) + DPIC (iterations) and require a
+ * two-stage derivation: PBKDF2-SHA256 then PBKDF2-SHA1. Older keybags use
+ * a single PBKDF2-SHA1 pass over SALT/ITER.
+ *
+ * @param {string|Buffer} password
+ * @param {object} attrs — from parseKeybag()
+ * @returns {Buffer} 32-byte key
+ */
+function deriveBackupKey(password, attrs) {
+  const pwd = Buffer.isBuffer(password) ? password : Buffer.from(String(password), "utf-8");
+  if (!attrs || !Buffer.isBuffer(attrs.SALT) || !attrs.ITER) {
+    throw new Error("deriveBackupKey: keybag missing SALT/ITER");
+  }
+  let material = pwd;
+  if (Buffer.isBuffer(attrs.DPSL) && attrs.DPIC) {
+    material = crypto.pbkdf2Sync(pwd, attrs.DPSL, attrs.DPIC, 32, "sha256");
+  }
+  return crypto.pbkdf2Sync(material, attrs.SALT, attrs.ITER, 32, "sha1");
+}
+
+/**
+ * RFC 3394 AES key unwrap. `kek` is the key-encryption key (16/24/32
+ * bytes); `wrapped` is (n+1) 64-bit blocks. Throws if the integrity
+ * check value does not match — i.e. wrong password.
+ *
+ * @param {Buffer} kek
+ * @param {Buffer} wrapped
+ * @returns {Buffer} unwrapped key (n*8 bytes)
+ */
+function aesUnwrap(kek, wrapped) {
+  if (!Buffer.isBuffer(wrapped) || wrapped.length % 8 !== 0 || wrapped.length < 16) {
+    throw new Error("aesUnwrap: wrapped key must be a multiple of 8 bytes (>=16)");
+  }
+  const n = wrapped.length / 8 - 1;
+  let A = Buffer.from(wrapped.subarray(0, 8));
+  const R = [];
+  for (let i = 0; i < n; i++) R.push(Buffer.from(wrapped.subarray(8 * (i + 1), 8 * (i + 2))));
+
+  for (let j = 5; j >= 0; j--) {
+    for (let i = n; i >= 1; i--) {
+      const t = n * j + i;
+      const At = Buffer.from(A);
+      xorCounter(At, t);
+      const B = aesEcbDecryptBlock(kek, Buffer.concat([At, R[i - 1]]));
+      A = Buffer.from(B.subarray(0, 8));
+      R[i - 1] = Buffer.from(B.subarray(8, 16));
+    }
+  }
+  if (!crypto.timingSafeEqual(A, RFC3394_IV)) {
+    throw new Error("aesUnwrap: integrity check failed (wrong password or corrupt key)");
+  }
+  return Buffer.concat(R);
+}
+
+/**
+ * RFC 3394 AES key wrap — inverse of aesUnwrap. Provided so tests (and
+ * any future re-wrap use) can build valid fixtures without a real backup.
+ *
+ * @param {Buffer} kek
+ * @param {Buffer} key — plaintext key (multiple of 8 bytes, >= 16)
+ * @returns {Buffer} wrapped (key.length + 8 bytes)
+ */
+function aesWrap(kek, key) {
+  if (!Buffer.isBuffer(key) || key.length % 8 !== 0 || key.length < 16) {
+    throw new Error("aesWrap: key must be a multiple of 8 bytes (>=16)");
+  }
+  const n = key.length / 8;
+  let A = Buffer.from(RFC3394_IV);
+  const R = [];
+  for (let i = 0; i < n; i++) R.push(Buffer.from(key.subarray(8 * i, 8 * (i + 1))));
+
+  for (let j = 0; j <= 5; j++) {
+    for (let i = 1; i <= n; i++) {
+      const B = aesEcbEncryptBlock(kek, Buffer.concat([A, R[i - 1]]));
+      A = Buffer.from(B.subarray(0, 8));
+      const t = n * j + i;
+      xorCounter(A, t);
+      R[i - 1] = Buffer.from(B.subarray(8, 16));
+    }
+  }
+  return Buffer.concat([A, ...R]);
+}
+
+// XOR a 64-bit big-endian counter into the last bytes of an 8-byte buffer.
+function xorCounter(buf8, t) {
+  // t fits in 53-bit safe-int range for any real keybag; spread over 8 bytes.
+  let v = t;
+  for (let k = 0; k < 8 && v > 0; k++) {
+    buf8[7 - k] ^= v & 0xff;
+    v = Math.floor(v / 256);
+  }
+}
+
+function aesEcbDecryptBlock(kek, block16) {
+  const d = crypto.createDecipheriv(ecbAlgoFor(kek), kek, null);
+  d.setAutoPadding(false);
+  return Buffer.concat([d.update(block16), d.final()]);
+}
+
+function aesEcbEncryptBlock(kek, block16) {
+  const c = crypto.createCipheriv(ecbAlgoFor(kek), kek, null);
+  c.setAutoPadding(false);
+  return Buffer.concat([c.update(block16), c.final()]);
+}
+
+function ecbAlgoFor(kek) {
+  switch (kek.length) {
+    case 16: return "aes-128-ecb";
+    case 24: return "aes-192-ecb";
+    case 32: return "aes-256-ecb";
+    default: throw new Error(`unsupported KEK length: ${kek.length}`);
+  }
+}
+
+/**
+ * Unwrap every passcode-protected class key in place, attaching `.KEY`.
+ * Class keys that are device-protected only (no WRAP_PASSCODE bit) cannot
+ * be unwrapped from a backup and are left without `.KEY`.
+ *
+ * @param {Object<number,object>} classKeys
+ * @param {Buffer} backupKey
+ * @returns {Object<number,object>} same object (mutated)
+ */
+function unwrapClassKeys(classKeys, backupKey) {
+  for (const clas of Object.keys(classKeys)) {
+    const ck = classKeys[clas];
+    if ((ck.WRAP & WRAP_PASSCODE) && Buffer.isBuffer(ck.WPKY)) {
+      ck.KEY = aesUnwrap(backupKey, ck.WPKY);
+    }
+  }
+  return classKeys;
+}
+
+/**
+ * Unwrap an EncryptionKey blob (`Manifest.plist.ManifestKey` or a file's
+ * `EncryptionKey`): 4-byte little-endian protection class followed by the
+ * wrapped key. Returns the unwrapped key bytes.
+ *
+ * @param {Object<number,object>} classKeys — with `.KEY` populated
+ * @param {Buffer} blob
+ * @returns {Buffer}
+ */
+function unwrapEncryptionKey(classKeys, blob) {
+  if (!Buffer.isBuffer(blob) || blob.length < 4 + 16) {
+    throw new Error("unwrapEncryptionKey: blob too short");
+  }
+  const clas = blob.readUInt32LE(0);
+  const wrapped = blob.subarray(4);
+  const ck = classKeys[clas];
+  if (!ck || !Buffer.isBuffer(ck.KEY)) {
+    throw new Error(`unwrapEncryptionKey: no unwrapped class key for protection class ${clas}`);
+  }
+  return aesUnwrap(ck.KEY, wrapped);
+}
+
+/**
+ * AES-256-CBC decrypt with a zero IV (iOS backup convention), no padding,
+ * optionally truncated to `size` (the real file length stored in the
+ * Files metadata; ciphertext is block-padded).
+ *
+ * @param {Buffer} key — 16/24/32 bytes
+ * @param {Buffer} data — ciphertext, multiple of 16 bytes
+ * @param {number} [size] — truncate plaintext to this many bytes
+ * @returns {Buffer}
+ */
+function decryptCBC(key, data, size) {
+  if (!Buffer.isBuffer(data) || data.length % 16 !== 0) {
+    throw new Error("decryptCBC: ciphertext length must be a multiple of 16");
+  }
+  const algo = key.length === 16 ? "aes-128-cbc" : key.length === 24 ? "aes-192-cbc" : "aes-256-cbc";
+  const iv = Buffer.alloc(16, 0);
+  const d = crypto.createDecipheriv(algo, key, iv);
+  d.setAutoPadding(false);
+  let out = Buffer.concat([d.update(data), d.final()]);
+  if (Number.isFinite(size) && size >= 0 && size < out.length) out = out.subarray(0, size);
+  return out;
+}
+
+/**
+ * Encrypt helper (zero-IV AES-CBC, PKCS-free block padding to 16) — used
+ * only by tests to build encrypted fixtures. Pads with zero bytes to the
+ * next 16-byte boundary, matching how we truncate on decrypt via `size`.
+ *
+ * @param {Buffer} key
+ * @param {Buffer} plaintext
+ * @returns {Buffer}
+ */
+function encryptCBC(key, plaintext) {
+  const pad = (16 - (plaintext.length % 16)) % 16;
+  const padded = pad ? Buffer.concat([plaintext, Buffer.alloc(pad, 0)]) : plaintext;
+  const algo = key.length === 16 ? "aes-128-cbc" : key.length === 24 ? "aes-192-cbc" : "aes-256-cbc";
+  const iv = Buffer.alloc(16, 0);
+  const c = crypto.createCipheriv(algo, key, iv);
+  c.setAutoPadding(false);
+  return Buffer.concat([c.update(padded), c.final()]);
+}
+
+module.exports = {
+  RFC3394_IV,
+  WRAP_PASSCODE,
+  parseKeybag,
+  deriveBackupKey,
+  aesUnwrap,
+  aesWrap,
+  unwrapClassKeys,
+  unwrapEncryptionKey,
+  decryptCBC,
+  encryptCBC,
+};