@ecopoesis/homebridge-dmx 0.1.0

package/tools/ghidra/string-walk.py

@@ -0,0 +1,180 @@
+# Find crypto/cipher code via string xrefs.
+#
+# Ghidra didn't auto-create RTTI symbols for XHL_Stick3CryptDmxUniverse etc.,
+# but the binary clearly contains:
+#   - typeinfo-name strings like "26XHL_DasNetCryptDmxUniverse"
+#     "N14XHL_Stick3ANet26XHL_Stick3CryptDmxUniverseE"
+#   - leaked source paths "../source/common/.../XHL_DasNetCryptDmxUniverse.cpp"
+#   - method-name strings in error logs like
+#     "[XHL_DasNetCryptDmxUniverse::setIoMode] pSubscribeUdpPort failed"
+#
+# Strategy: for each interesting string, locate its bytes in memory and find
+# every function that references it. That function IS the method whose name
+# the string mentions (since the string is its diagnostic log message), or
+# AT LEAST a function in the crypto path.
+
+# @category Stick
+
+import os, re
+from ghidra.app.decompiler import DecompInterface
+from ghidra.util.task import ConsoleTaskMonitor
+from ghidra.program.model.address import AddressSet
+from ghidra.program.model.listing import CodeUnit
+
+OUT_DIR = os.path.join(os.path.dirname(getSourceFile().getAbsolutePath()), 'out4')
+try:
+    os.makedirs(OUT_DIR)
+except OSError:
+    pass
+
+prog = currentProgram
+fm = prog.getFunctionManager()
+mem = prog.getMemory()
+listing = prog.getListing()
+ref_mgr = prog.getReferenceManager()
+monitor = ConsoleTaskMonitor()
+decomp = DecompInterface()
+decomp.openProgram(prog)
+
+
+def find_string_addrs(needle):
+    """Return all addresses in memory where the literal bytes of `needle`
+    occur (followed by a NUL byte for safety)."""
+    pattern = needle.encode('utf-8') + b'\x00'
+    hits = []
+    # Use Memory.findBytes
+    addr = mem.findBytes(prog.getMinAddress(), pattern, None, True, monitor)
+    while addr is not None and len(hits) < 50:
+        hits.append(addr)
+        nxt = addr.add(1)
+        try:
+            addr = mem.findBytes(nxt, pattern, None, True, monitor)
+        except Exception:
+            break
+    return hits
+
+
+def dump_function(func, out):
+    out.write('==== %s @ %s ====\n' % (func.getName(True), func.getEntryPoint()))
+    out.write('signature: %s\n' % func.getPrototypeString(True, True))
+    out.write('size: %d body bytes\n' % func.getBody().getNumAddresses())
+    callees = sorted(set('%s @ %s' % (f.getName(True), f.getEntryPoint())
+                         for f in func.getCalledFunctions(monitor)))
+    out.write('\n-- callees (%d) --\n' % len(callees))
+    for c in callees:
+        out.write('  ' + c + '\n')
+    callers = sorted(set('%s @ %s' % (f.getName(True), f.getEntryPoint())
+                         for f in func.getCallingFunctions(monitor)))
+    out.write('\n-- callers (%d) --\n' % len(callers))
+    for c in callers:
+        out.write('  ' + c + '\n')
+    out.write('\n-- decompilation --\n')
+    res = decomp.decompileFunction(func, 180, monitor)
+    if res.decompileCompleted():
+        out.write(res.getDecompiledFunction().getC())
+    else:
+        out.write('(decompilation failed: %s)\n' % res.getErrorMessage())
+    out.write('\n')
+
+
+# (needle, suggested filename slug)
+NEEDLES = [
+    # Source file paths leak class boundaries
+    ('XHL_DasNetCryptDmxUniverse.cpp',          'XHL_DasNetCryptDmxUniverse_cpp'),
+    ('XHL_DasEccAesCryptography.cpp',           'XHL_DasEccAesCryptography_cpp'),
+    ('XHL_DasEccStreamCryptography.cpp',        'XHL_DasEccStreamCryptography_cpp'),
+    ('XHL_DasDhRsaCryptography.hpp',            'XHL_DasDhRsaCryptography_hpp'),
+
+    # Error/debug strings that contain method names
+    ('XHL_DasNetCryptDmxUniverse::setIoMode',   'setIoMode'),
+
+    # RTTI strings — anything that references them is the typeinfo struct
+    # for that class, and the vtable points at it.
+    ('N14XHL_Stick3ANet26XHL_Stick3CryptDmxUniverseE',  'Stick3CryptDmxUniverse_rtti'),
+    ('N14XHL_Stick5ANet26XHL_Stick5CryptDmxUniverseE',  'Stick5CryptDmxUniverse_rtti'),
+    ('26XHL_DasNetCryptDmxUniverse',                     'DasNetCryptDmxUniverse_rtti'),
+    ('14XHL_AesOStream',                                  'AesOStream_rtti'),
+    ('14XHL_AesIStream',                                  'AesIStream_rtti'),
+    ('20XHL_AesOStreamBuffer',                            'AesOStreamBuffer_rtti'),
+    ('20XHL_AesIStreamBuffer',                            'AesIStreamBuffer_rtti'),
+    ('25XHL_DasEccAesCryptography',                       'DasEccAesCryptography_rtti'),
+    ('24XHL_DasDhRsaCryptographyILj1024EE',               'DasDhRsaCryptography_1024_rtti'),
+    ('24XHL_DasDhRsaCryptographyILj512EE',                'DasDhRsaCryptography_512_rtti'),
+    ('28XHL_DasEccStreamCryptography',                    'DasEccStreamCryptography_rtti'),
+    ('19XHL_DasCryptography',                             'DasCryptography_rtti'),
+]
+
+summary = open(os.path.join(OUT_DIR, 'SUMMARY.txt'), 'w')
+summary.write('String-walk anchors — ESA2 HardwareManager (2024-03-21)\n\n')
+
+seen_funcs = set()
+
+for needle, slug in NEEDLES:
+    summary.write('\n#### needle: %r\n' % needle)
+    str_addrs = find_string_addrs(needle)
+    summary.write('  found %d occurrence(s) of string\n' % len(str_addrs))
+    if not str_addrs:
+        continue
+
+    for str_addr in str_addrs:
+        summary.write('    @ %s\n' % str_addr)
+
+        # Walk one ref-hop: who references this string?
+        L1_refs = list(ref_mgr.getReferencesTo(str_addr))
+        L1_funcs = set()
+        L1_data_addrs = set()
+        for r in L1_refs:
+            fa = r.getFromAddress()
+            f = fm.getFunctionContaining(fa)
+            if f is not None:
+                L1_funcs.add(f.getEntryPoint())
+            else:
+                L1_data_addrs.add(fa)
+
+        summary.write('      direct fn refs: %d\n' % len(L1_funcs))
+        for ep in sorted(L1_funcs):
+            f = fm.getFunctionAt(ep)
+            summary.write('        %s @ %s\n' % (f.getName(True), f.getEntryPoint()))
+
+        summary.write('      direct data refs: %d\n' % len(L1_data_addrs))
+        for da in sorted(L1_data_addrs):
+            summary.write('        data @ %s\n' % da)
+            # Walk one more hop: who references THAT data location?
+            L2_refs = list(ref_mgr.getReferencesTo(da))
+            for r2 in L2_refs:
+                fa2 = r2.getFromAddress()
+                f2 = fm.getFunctionContaining(fa2)
+                if f2 is not None:
+                    L1_funcs.add(f2.getEntryPoint())
+                    summary.write('          via %s -> fn %s @ %s\n' %
+                                  (da, f2.getName(True), f2.getEntryPoint()))
+                else:
+                    # Could be the vtable structure itself
+                    summary.write('          via %s -> data @ %s\n' % (da, fa2))
+                    # And one more hop (vtable -> referencing fn)
+                    for r3 in ref_mgr.getReferencesTo(fa2):
+                        fa3 = r3.getFromAddress()
+                        f3 = fm.getFunctionContaining(fa3)
+                        if f3 is not None:
+                            L1_funcs.add(f3.getEntryPoint())
+                            summary.write('            via %s -> fn %s @ %s\n' %
+                                          (fa2, f3.getName(True),
+                                           f3.getEntryPoint()))
+
+        # Dump every collected function
+        for ep in sorted(L1_funcs):
+            if ep in seen_funcs:
+                continue
+            seen_funcs.add(ep)
+            f = fm.getFunctionAt(ep)
+            if f is None:
+                continue
+            safe = re.sub(r'[^A-Za-z0-9._-]', '_', f.getName(True))[:140]
+            path = os.path.join(OUT_DIR, '%s_%s_%s.txt' %
+                                (slug, f.getEntryPoint(), safe))
+            with open(path, 'w') as o:
+                dump_function(f, o)
+
+summary.write('\n=== total functions dumped: %d ===\n' % len(seen_funcs))
+summary.close()
+print('string-walk: dumped %d functions to %s' % (len(seen_funcs), OUT_DIR))

package/tools/hmac-key.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Extract the 0x48 TCP-auth HMAC key from a running debug Hardware Manager.
+#
+# The 0x48 handshake is authenticated with HMAC-SHA256(key, msg[0:82]); the
+# key is an internal HWM constant. This attaches lldb, breakpoints the HMAC
+# routine, and dumps the key the instant HWM builds a 0x48 (one hit, then
+# detaches — not a per-frame breakpoint, so HWM stays healthy).
+#
+# Steps:
+#   1. Quit the normal Hardware Manager (it holds the Stick's single session).
+#   2. Launch the debug copy:   tools/pathA-launch-hwm.sh
+#      Leave it DISCONNECTED from the Stick for now.
+#   3. Run this script.
+#   4. When it prints "waiting for the 0x48 handshake", connect the debug HWM
+#      to the Stick (Connection -> Add/Connect). The key is dumped + logged.
+
+set -uo pipefail
+cd "$(dirname "$0")/.."
+
+SCAN_PY="tools/lldb_hmac_key.py"
+LOG="/tmp/stick-hmac-key.log"
+
+PID="$(pgrep -f '/tmp/HM-ESA2-dbg.app/Contents/MacOS/HardwareManager' | head -1)"
+if [ -z "$PID" ]; then
+  echo "ERROR: the debug Hardware Manager is not running."
+  echo "  1. Quit the normal Hardware Manager."
+  echo "  2. Run:  tools/pathA-launch-hwm.sh"
+  echo "  3. Leave it DISCONNECTED from the Stick, then re-run this script."
+  exit 1
+fi
+
+echo ">>> debug HWM pid = $PID"
+echo ">>> attaching lldb and arming the HMAC breakpoint ..."
+echo ">>> when it says 'waiting for the 0x48 handshake', CONNECT HWM to the Stick."
+echo
+
+timeout 600 lldb --batch \
+  -o "command script import $SCAN_PY" \
+  -o "detach" \
+  -o "quit" \
+  -p "$PID" 2>&1 | sed 's/^/  /'
+
+echo
+if grep -q 'auth HMAC caught' "$LOG" 2>/dev/null; then
+  echo ">>> SUCCESS — the auth key:"
+  grep -E 'key length|key \(hex\)|key \(text\)' "$LOG" | sed 's/^/  /'
+  echo ">>> full log: $LOG"
+else
+  echo "!!! the 0x48 HMAC was not caught — did HWM connect to the Stick?"
+  echo "    log: $LOG"
+fi

package/tools/hwm-entitlements.plist

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>com.apple.security.get-task-allow</key>
+	<true/>
+	<key>com.apple.security.cs.disable-library-validation</key>
+	<true/>
+	<key>com.apple.security.cs.allow-dyld-environment-variables</key>
+	<true/>
+	<key>com.apple.security.cs.disable-executable-page-protection</key>
+	<true/>
+	<key>com.apple.security.cs.allow-jit</key>
+	<true/>
+	<key>com.apple.security.cs.allow-unsigned-executable-memory</key>
+	<true/>
+</dict>
+</plist>

package/tools/inspect-plaintext.mjs

@@ -0,0 +1,87 @@
+// Decrypt every 576-byte UDP DMX frame in a pcap and dump the FULL 544-byte
+// plaintext layout: [0:16] P0 header, [16:528] 512 DMX, [528:544] trailer.
+// The question: is the 16-byte trailer zero (what send_dmx sends) or a
+// per-frame checksum the Stick validates?
+//
+//   node tools/inspect-plaintext.mjs <pcap> <key-hex>
+
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+
+const [, , pcapPath, keyHex] = process.argv;
+if (!pcapPath || !keyHex) { console.error('usage: inspect-plaintext.mjs <pcap> <key-hex>'); process.exit(1); }
+const key = Buffer.from(keyHex.replace(/\s/g, ''), 'hex');
+if (key.length !== 32) { console.error('key must be 32 bytes'); process.exit(1); }
+
+const buf = fs.readFileSync(pcapPath);
+const le = buf.readUInt32LE(0) === 0xa1b2c3d4;
+const linkType = le ? buf.readUInt32LE(20) : buf.readUInt32BE(20);
+const ethSkip = linkType === 1 ? 14 : 4;
+
+const frames = [];
+let off = 24;
+while (off + 16 <= buf.length) {
+  const capLen = le ? buf.readUInt32LE(off + 8) : buf.readUInt32BE(off + 8);
+  off += 16;
+  if (off + capLen > buf.length) break;
+  const pkt = buf.subarray(off, off + capLen);
+  off += capLen;
+  if (pkt.length < ethSkip + 28) continue;
+  const ip = pkt.subarray(ethSkip);
+  if (ip[9] !== 17) continue;
+  const udp = ip.subarray((ip[0] & 0x0f) * 4);
+  const payload = udp.subarray(8, udp.readUInt16BE(4));
+  if (payload.length === 576 && payload.subarray(0, 8).toString() === 'Stick_3A')
+    frames.push(Buffer.from(payload));
+}
+console.log(`${frames.length} 576-byte frames in ${pcapPath}\n`);
+
+function decrypt(frame) {
+  const h = frame.subarray(0, 32);
+  const iv = Buffer.concat([h.subarray(0x0a, 0x12), h.subarray(0x18, 0x20)]);
+  const d = crypto.createDecipheriv('aes-256-cbc', key, iv);
+  d.setAutoPadding(false);
+  return Buffer.concat([d.update(frame.subarray(32)), d.final()]);
+}
+const zr = (b) => { let z = 0; for (const x of b) if (x === 0) z++; return z / b.length; };
+
+let decoded = 0;
+const p0set = new Map(), trailerSet = new Map();
+const trailerSamples = [];
+for (let i = 0; i < frames.length; i++) {
+  const pt = decrypt(frames[i]);
+  const dmx = pt.subarray(16, 528);
+  if (zr(dmx) < 0.5) continue;             // not this session's key
+  decoded++;
+  const p0 = pt.subarray(0, 16).toString('hex');
+  const tr = pt.subarray(528, 544).toString('hex');
+  p0set.set(p0, (p0set.get(p0) || 0) + 1);
+  trailerSet.set(tr, (trailerSet.get(tr) || 0) + 1);
+  if (decoded <= 6) {
+    const h = frames[i].subarray(0, 32);
+    const lit = [];
+    for (let c = 0; c < 512; c++) if (dmx[c]) lit.push(`ch${c+1}=${dmx[c]}`);
+    trailerSamples.push({
+      fieldA: h.readUInt32LE(0x0a), seq: h[0x17],
+      p0, tr, nLit: lit.length, lit: lit.slice(0, 8).join(' '),
+    });
+  }
+}
+
+console.log(`frames that decrypt with this key: ${decoded}/${frames.length}\n`);
+if (!decoded) { console.log('key does not match any frame in this pcap'); process.exit(1); }
+
+console.log('first 6 decrypted frames:');
+for (const s of trailerSamples) {
+  console.log(`  fieldA=${String(s.fieldA).padEnd(6)} seq=${String(s.seq).padEnd(4)} lit=${s.nLit}`);
+  console.log(`    P0      = ${s.p0}`);
+  console.log(`    trailer = ${s.tr}`);
+  if (s.lit) console.log(`    dmx     = ${s.lit}`);
+}
+console.log(`\nP0 distinct values    : ${p0set.size}`);
+for (const [v, n] of p0set) console.log(`    ${v}  x${n}`);
+console.log(`trailer distinct values: ${trailerSet.size}`);
+for (const [v, n] of [...trailerSet].slice(0, 8)) console.log(`    ${v}  x${n}`);
+console.log(trailerSet.size === 1
+  ? '\n  => trailer is CONSTANT — send_dmx sending zeros is wrong only if this constant != 0'
+  : '\n  => trailer VARIES per frame — it is a checksum/MAC; send_dmx sending zeros is FATAL');

package/tools/lldb-capture-aes.py

@@ -0,0 +1,137 @@
+"""
+lldb script to capture AES keys from HardwareManager.
+Attach to HardwareManager, then source this script.
+
+Usage:
+  lldb -p <PID>
+  (lldb) command script import /path/to/lldb-capture-aes.py
+  (lldb) continue
+
+Then connect to the Stick in the HardwareManager UI.
+Keys will be printed and saved to /tmp/stick-aes-keys.log
+"""
+
+import lldb
+import os
+
+LOG_PATH = "/tmp/stick-aes-keys.log"
+key_count = 0
+
+def log(msg):
+    with open(LOG_PATH, "a") as f:
+        f.write(msg + "\n")
+    print(msg)
+
+def on_setkey_enc(frame, bp_loc, dict):
+    global key_count
+    key_count += 1
+    thread = frame.GetThread()
+    process = thread.GetProcess()
+
+    # x86_64 calling convention: rdi=ctx, rsi=key, edx=keybits
+    keybits = frame.FindRegister("edx").GetValueAsUnsigned()
+    key_ptr = frame.FindRegister("rsi").GetValueAsUnsigned()
+    key_len = keybits // 8
+
+    err = lldb.SBError()
+    key_bytes = process.ReadMemory(key_ptr, key_len, err)
+
+    if err.Success() and key_bytes:
+        hex_key = " ".join(f"{b:02x}" for b in key_bytes)
+        log(f"[{key_count}] AES_SETKEY_ENC bits={keybits} key={hex_key}")
+
+        # Save raw key to file
+        with open("/tmp/stick-aes-key.bin", "wb") as f:
+            f.write(key_bytes)
+        log(f"    Raw key saved to /tmp/stick-aes-key.bin")
+    else:
+        log(f"[{key_count}] AES_SETKEY_ENC bits={keybits} (failed to read key: {err})")
+
+    # Don't stop, continue running
+    return False
+
+def on_setkey_dec(frame, bp_loc, dict):
+    global key_count
+    key_count += 1
+    thread = frame.GetThread()
+    process = thread.GetProcess()
+
+    keybits = frame.FindRegister("edx").GetValueAsUnsigned()
+    key_ptr = frame.FindRegister("rsi").GetValueAsUnsigned()
+    key_len = keybits // 8
+
+    err = lldb.SBError()
+    key_bytes = process.ReadMemory(key_ptr, key_len, err)
+
+    if err.Success() and key_bytes:
+        hex_key = " ".join(f"{b:02x}" for b in key_bytes)
+        log(f"[{key_count}] AES_SETKEY_DEC bits={keybits} key={hex_key}")
+    else:
+        log(f"[{key_count}] AES_SETKEY_DEC bits={keybits} (failed to read key: {err})")
+
+    return False
+
+def on_crypt_cbc(frame, bp_loc, dict):
+    thread = frame.GetThread()
+    process = thread.GetProcess()
+
+    # rdi=ctx, esi=mode, rdx=length, rcx=iv, r8=input, r9=output
+    mode = frame.FindRegister("esi").GetValueAsUnsigned()
+    length = frame.FindRegister("rdx").GetValueAsUnsigned()
+
+    mode_str = "ENC" if mode == 1 else "DEC"
+    log(f"    AES_CBC {mode_str} len={length}")
+
+    return False
+
+def __lldb_init_module(debugger, internal_dict):
+    target = debugger.GetSelectedTarget()
+    if not target:
+        print("ERROR: No target. Attach to HardwareManager first.")
+        return
+
+    # Clear old log
+    with open(LOG_PATH, "w") as f:
+        f.write("=== lldb AES key capture started ===\n")
+
+    # Find the mbedcrypto module
+    found_module = None
+    for module in target.module_iter():
+        name = module.GetFileSpec().GetFilename()
+        if name and "mbedcrypto" in name:
+            found_module = module
+            break
+
+    if not found_module:
+        print("WARNING: libmbedcrypto not found in loaded modules")
+        print("Available modules:")
+        for module in target.module_iter():
+            print(f"  {module.GetFileSpec()}")
+        return
+
+    print(f"Found: {found_module.GetFileSpec()}")
+
+    # Set breakpoints on the symbols
+    bp_enc = target.BreakpointCreateByName("mbedtls_aes_setkey_enc", found_module.GetFileSpec().GetFilename())
+    if bp_enc.IsValid():
+        bp_enc.SetScriptCallbackFunction("lldb_capture_aes.on_setkey_enc")
+        bp_enc.SetAutoContinue(True)
+        print(f"Breakpoint on mbedtls_aes_setkey_enc: {bp_enc}")
+    else:
+        print("ERROR: Could not set breakpoint on mbedtls_aes_setkey_enc")
+
+    bp_dec = target.BreakpointCreateByName("mbedtls_aes_setkey_dec", found_module.GetFileSpec().GetFilename())
+    if bp_dec.IsValid():
+        bp_dec.SetScriptCallbackFunction("lldb_capture_aes.on_setkey_dec")
+        bp_dec.SetAutoContinue(True)
+        print(f"Breakpoint on mbedtls_aes_setkey_dec: {bp_dec}")
+
+    bp_cbc = target.BreakpointCreateByName("mbedtls_aes_crypt_cbc", found_module.GetFileSpec().GetFilename())
+    if bp_cbc.IsValid():
+        bp_cbc.SetScriptCallbackFunction("lldb_capture_aes.on_crypt_cbc")
+        bp_cbc.SetAutoContinue(True)
+        print(f"Breakpoint on mbedtls_aes_crypt_cbc: {bp_cbc}")
+
+    log("Breakpoints set. Connect to the Stick in the UI, then check this log.")
+    print(f"\nReady! Keys will be logged to {LOG_PATH}")
+    print("Now type 'continue' and connect to the Stick in the UI.")

package/tools/lldb_hmac_key.py

@@ -0,0 +1,93 @@
+"""
+Extract the 0x48 TCP-auth HMAC key from a running Hardware Manager.
+
+The 0x48 handshake message ends with HMAC-SHA256(key, msg[0:82]). The key is
+an internal HWM constant we can't derive offline. But the HMAC routine
+FUN_1004080b0 receives it directly:
+
+    FUN_1004080b0(rdi=key, rsi=keylen, rdx=msg, rcx=msglen, r8=out, r9=32)
+
+When HWM builds the 0x48 it calls this with rcx (msglen) == 0x52. We set one
+breakpoint on FUN_1004080b0, and on the call where rcx==0x52 we dump rdi/rsi
+— that's the key. One hit, then detach. Not a per-frame breakpoint, so it
+won't starve HWM the way the old encrypt-path breakpoints did.
+
+Usage (driven by tools/hmac-key.sh):
+  lldb -p <PID> --batch \
+       -o "command script import tools/lldb_hmac_key.py" -o "detach" -o "quit"
+Then in HWM: disconnect from the Stick and reconnect.
+"""
+
+import sys
+
+try:
+    import lldb
+except ImportError:
+    lldb = None
+
+HMAC_FN_FILEADDR = 0x1004080b0   # FUN_1004080b0 — HMAC-SHA256
+LOG_PATH = "/tmp/stick-hmac-key.log"
+_logf = None
+
+
+def log(m=""):
+    print(m)
+    sys.stdout.flush()
+    if _logf:
+        _logf.write(m + "\n")
+        _logf.flush()
+
+
+def hexs(b):
+    return "".join("%02x" % x for x in bytearray(b))
+
+
+def hmac_bp_callback(frame, bp_loc, internal_dict):
+    """Fires on every FUN_1004080b0 call; reports the one for the 0x48 (msglen 0x52)."""
+    process = frame.GetThread().GetProcess()
+    reg = lambda n: frame.FindRegister(n).GetValueAsUnsigned()
+    key, keylen, msglen = reg("rdi"), reg("rsi"), reg("rcx")
+    if msglen != 0x52:
+        return False   # not the 0x48 auth HMAC — keep going
+    err = lldb.SBError()
+    n = keylen if 0 < keylen <= 512 else 64
+    kd = process.ReadMemory(key, n, err)
+    md = process.ReadMemory(reg("rdx"), 0x52, err)
+    log("")
+    log(">>> 0x48 auth HMAC caught")
+    log("    key length : %d" % keylen)
+    log("    key (hex)  : %s" % (hexs(kd) if kd else "(unreadable)"))
+    if kd:
+        try:
+            log("    key (text) : %r" % bytearray(kd).decode("utf-8"))
+        except Exception:
+            log("    key (text) : (not utf-8)")
+    log("    msg[0:82]  : %s" % (hexs(md) if md else "(unreadable)"))
+    log("")
+    log(">>> got it — detaching.")
+    return True    # stop so the batch script can detach
+
+
+def __lldb_init_module(debugger, internal_dict):
+    global _logf
+    _logf = open(LOG_PATH, "w")
+    log("=== HMAC-key extraction %s ===" % __import__("time").ctime())
+    target = debugger.GetSelectedTarget()
+    process = target.GetProcess()
+
+    saddr = target.ResolveFileAddress(HMAC_FN_FILEADDR)
+    laddr = saddr.GetLoadAddress(target)
+    log("HMAC fn  file 0x%x  ->  load 0x%x" % (HMAC_FN_FILEADDR, laddr))
+
+    bp = target.BreakpointCreateByAddress(laddr)
+    bp.SetScriptCallbackFunction("lldb_hmac_key.hmac_bp_callback")
+    if bp.GetNumLocations() == 0:
+        log("!!! breakpoint resolved 0 locations — wrong address/module")
+        return
+    log("breakpoint armed on the HMAC function (%d location)" % bp.GetNumLocations())
+    log("")
+    log(">>> NOW: in HWM, disconnect from the Stick and reconnect.")
+    log(">>> waiting for the 0x48 handshake ...")
+
+    process.Continue()   # blocks until the 0x48 HMAC call stops us
+    log(">>> done — log at %s" % LOG_PATH)