Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
23.7 KB
Raw Blame
// CustomFirmwareCacheLoader.swift — open launchd_cache_loader's unsecure-cache gate.
//
// Swift port of `scripts/patchers/cfw_patch_cache_loader.py`, driven today by
// `cfw.py patch-launchd-cache-loader <binary>`.
//
// What the binary does. `/usr/libexec/launchd_cache_loader` hands launchd the
// XPC service cache, `/System/Library/xpc/launchd.plist`, at boot. Normally it
// checks the file against its detached signature `launchd.plist.sig` and asks
// AMFI whether that signature's cdhash is in a trust cache (see
// `CustomFirmwareDetachedSignature`). The boot-arg `launchd_unsecure_cache=` in
// `kern.bootargs` skips that check:
//
//     adrp x0, "kern.bootargs" ; add x0, x0, #… ; add x1, sp, #…
//     bl   <sysctl-by-name helper>
//     cbz  x0, no_bootargs
//     ldr  x0, [sp, #…] ; cbz x0, no_bootargs
//     adrp x1, "launchd_unsecure_cache=" ; add x1, x1, #…   <- the string xref
//     mov  x2, #0
//     bl   <boot-arg lookup>                                <- the call
//     cbz  x0, skip_unsecure_cache                          <- THE GATE
//     …                                                     <- "Using unsecure cache: %s"
//
// On a VM there is no way to set that boot-arg, so the gate always takes the
// skip and the loader refuses a cache whose signature is not trusted. NOP'ing
// the one `cbz` makes the unsecure path unconditional, which is what lets a
// MODIFIED `/System/Library/xpc/launchd.plist` be loaded — the only reason this
// patch exists (`Research/0_binary_patch_comparison.md`, "Allow modified
// launchd.plist"). A flavour that does not rewrite `launchd.plist` does not
// need it (see `cfw-kit/lib/base_stages.sh:stage_launchd_cache_loader`), and
// neither does one that re-signs it and puts the new cdhashes in the static
// trust cache, which is what the restore image (`minimal`) does.
//
// Nothing is hardcoded. The boot-arg string is found by content in the Mach-O's
// own string sections, its ADRP+ADD xref is recovered from Capstone-decoded
// operands, the call after it is found by control flow, and the gate is the
// conditional branch that consumes that call's return register. The replacement
// is `ARM64.nop`, which ARM64Constants generated with keystone.
//
// Two deliberate divergences from the Python, both documented at the site:
//
//  1. IDEMPOTENCE. The Python is not idempotent. On a second run it walks past
//     the NOP it wrote and takes the *next* conditional branch — `cbnz x0,`
//     over the log-file `fopen` — so it silently re-opens and truncates the log
//     on every cache build. This port recognises its own output and stops.
//     `CryptexFilesystemPatcher.patchLaunchdCacheLoader` patches in place with
//     no `.bak` restore, so that second run is reachable today.
//  2. REFUSAL OVER GUESSING. The Python takes the first conditional branch it
//     sees after the call, whatever it tests. This port checks that the branch
//     really consumes the call's result and jumps forward out of the unsecure
//     path, and throws when it does not, rather than NOP'ing an unrelated
//     branch on a firmware whose shape has moved.
//
// Re-signing is OFF by default, which is what keeps this byte-identical to the
// Python: every shipped caller re-signs the whole binary afterwards (`ldid_sign`
// in `cfw_install*.sh`, `VPhoneSigner.sign` in the Swift call site), so slot
// hashes written here would be thrown away. A caller that does NOT re-sign must
// pass `reattestsCodeSignature: true` or ship a binary TXM will SIGKILL on the
// first page-in of the patched page.

import Foundation
import VPhonePatchKit

/// NOPs the `launchd_unsecure_cache=` gate in `/usr/libexec/launchd_cache_loader`.
public enum CustomFirmwareCacheLoaderPatcher {
    // MARK: - Identity

    /// Component name, matching the Python's `records.set_group`.
    public static let component = "launchd_cache_loader"

    /// Record identity, matching the Python's `records.site` label so a captured
    /// reference and this port sort together.
    public static let patchID = "system-launchd_cache_loader-boot-unsecure_cache_gate"

    /// Substrings that name the gate's boot-arg, most specific first. The same
    /// list the Python carries: the later three are there for a firmware that
    /// renames the boot-arg, and have never matched on a shipping build.
    public static let anchorTokens = ["unsecure_cache", "unsecure", "cache_valid", "validation"]

    // MARK: - Search windows

    /// How far an ADD may sit from the ADRP it completes. Both are emitted by
    /// the same relocation pair, so the compiler keeps them close; 8 is the
    /// Python's window.
    static let maxADRPToADDInstructions = 8

    /// How far past the string xref to look for the call it is an argument to.
    static let maxInstructionsToCall = 16

    /// How far past that call the branch on its result may sit.
    static let maxInstructionsAfterCall = 8

    /// The no-call fallback window, used only when no call follows the xref.
    static let maxFallbackInstructions = 32

    /// Where progress goes when the caller does not say. The Python prints to
    /// stdout and `cfw_install*.sh` captures that, so this does too.
    public static let stdoutLog: @Sendable (String) -> Void = { print($0) }

    // MARK: - Patching

    /// Open the gate in the `launchd_cache_loader` at `url`.
    ///
    /// Idempotent: a binary this has already patched is reported
    /// `.alreadyPatched` and left untouched, byte for byte.
    ///
    /// - Parameter reattestsCodeSignature: recompute the code-directory slot
    ///   hash of the page the NOP lands in. Off by default because every
    ///   shipped caller re-signs the binary wholesale afterwards; a caller that
    ///   does not MUST set it, or TXM SIGKILLs the guest process.
    /// - Throws: ``PatcherError/patchSiteNotFound(_:)`` when the boot-arg
    ///   string, its xref, or a branch with the gate's shape is missing — each
    ///   of which means the firmware moved and has to stop the install rather
    ///   than be guessed at.
    @discardableResult
    public static func patch(
        fileAt url: URL,
        dryRun: Bool = false,
        reattestsCodeSignature: Bool = false,
        log: ((String) -> Void)? = stdoutLog,
    ) throws -> Report {
        guard FileManager.default.fileExists(atPath: url.path) else {
            throw PatcherError.fileNotFound(url.path)
        }
        var data = try Data(contentsOfFileToRewrite: url)
        let report = try patch(
            &data,
            dryRun: dryRun,
            reattestsCodeSignature: reattestsCodeSignature,
            log: log,
        )
        if !dryRun, report.sitesWritten > 0 || !report.reattestedSlots.isEmpty {
            try data.write(to: url)
        }
        return report
    }

    /// In-memory form, for callers that already hold the binary.
    ///
    /// `data` is left untouched unless the run writes, so an `.alreadyPatched`
    /// or `.wouldPatch` result cannot change a byte.
    @discardableResult
    public static func patch(
        _ data: inout Data,
        dryRun: Bool = false,
        reattestsCodeSignature: Bool = false,
        log: ((String) -> Void)? = stdoutLog,
    ) throws -> Report {
        // Every offset below is an absolute file offset, so the buffer has to be
        // zero-based — a slice handed in by a caller is not.
        if data.startIndex != 0 {
            data = Data(data)
        }

        let located = try locateGate(in: data)
        let anchor = located.anchor
        let gate = located.gate

        if anchor.text == anchor.token {
            log?("  Found anchor '\(anchor.token)' at va:0x\(hex(anchor.stringVMA))")
        } else {
            log?("  Found anchor '\(anchor.token)' inside \"\(anchor.text)\"")
            log?("    String start: va:0x\(hex(anchor.stringVMA))  "
                + "(match at va:0x\(hex(anchor.matchVMA)))")
        }
        log?("  Found string ref at 0x\(hex(UInt64(anchor.referenceFileOffset)))")
        if let callVMA = gate.callVMA {
            log?("    Call at va:0x\(hex(callVMA)); gate tests its result")
        }

        guard !gate.wasAlreadyNOP else {
            // The Python has no such branch: it walks past its own NOP and takes
            // the next conditional branch, which on this binary is the `cbnz`
            // guarding the log-file `fopen`. Stopping here is the whole
            // difference between running the installer twice and corrupting the
            // binary on the second pass.
            log?("  [=] already NOP at 0x\(hex(UInt64(gate.fileOffset))); nothing to do")
            // Re-attestation still runs when asked for: a binary the Python
            // patched carries a stale slot hash, and this is the one call that
            // can repair it without rewriting an instruction. It returns nothing
            // when the stored hashes already match, so the idempotent case stays
            // byte-stable.
            var slots: [CustomFirmwareSlotRehash] = []
            if reattestsCodeSignature, !dryRun {
                slots = try CustomFirmwareMachOCodeSignature.reattest(&data, modifiedOffsets: [gate.fileOffset])
                for slot in slots {
                    log?("    re-attested \(slot)")
                }
            }
            return Report(
                outcome: .alreadyPatched,
                anchor: anchor,
                gate: gate,
                record: nil,
                reattestedSlots: slots,
            )
        }

        let nop = ARM64.nop
        let original = Data(data[gate.fileOffset ..< gate.fileOffset + nop.count])

        log?("  Before:")
        log?(context(in: data, around: gate, marking: gate.fileOffset))

        guard !dryRun else {
            log?("  [.] dry-run: would NOP \(gate.text) at 0x\(hex(UInt64(gate.fileOffset)))")
            return Report(
                outcome: .wouldPatch,
                anchor: anchor,
                gate: gate,
                record: nil,
                reattestedSlots: [],
            )
        }

        data.replaceSubrange(gate.fileOffset ..< gate.fileOffset + nop.count, with: nop)

        log?("  After:")
        log?(context(in: data, around: gate, marking: gate.fileOffset))

        let written = Data(data[gate.fileOffset ..< gate.fileOffset + nop.count])
        guard written == nop else {
            throw PatcherError.patchVerificationFailed(
                "\(component): gate at 0x\(hex(UInt64(gate.fileOffset))) reads \(written.hex) after write",
            )
        }

        var slots: [CustomFirmwareSlotRehash] = []
        if reattestsCodeSignature {
            slots = try CustomFirmwareMachOCodeSignature.reattest(&data, modifiedOffsets: [gate.fileOffset])
            for slot in slots {
                log?("    re-attested \(slot)")
            }
        }

        log?("  [+] NOPped at 0x\(hex(UInt64(gate.fileOffset)))")

        return Report(
            outcome: .patched,
            anchor: anchor,
            gate: gate,
            record: record(anchor: anchor, gate: gate, original: original, patched: nop),
            reattestedSlots: slots,
        )
    }

    // MARK: - Locating the gate

    /// Find the gate without touching the binary.
    ///
    /// The three failure modes are reported apart, because they mean different
    /// things: no boot-arg string at all (not this binary), a string with no
    /// xref (the check was compiled out), and an xref whose branch no longer has
    /// the gate's shape (the function was rewritten).
    public static func locateGate(in data: Data) throws -> (anchor: Anchor, gate: Gate) {
        let data = data.startIndex == 0 ? data : Data(data)
        let sections = MachOParser.parseSections(from: data)
        guard !sections.isEmpty else {
            throw PatcherError.invalidFormat("not a 64-bit Mach-O, or it carries no sections")
        }
        guard let text = sections["__TEXT,__text"] else {
            throw PatcherError.invalidFormat("__TEXT,__text not found")
        }

        var firstFound: StringHit?
        for hit in stringHits(in: data, sections: sections) {
            if firstFound == nil {
                firstFound = hit
            }
            // The code addresses the string's first byte, so that VA is tried
            // first; the substring's own VA is the Python's fallback, for a
            // compiler that split the literal.
            let candidates = hit.stringVMA == hit.matchVMA
                ? [hit.stringVMA]
                : [hit.stringVMA, hit.matchVMA]
            guard let reference = candidates.lazy.compactMap({ target in
                findStringReference(in: data, text: text, targetVMA: target)
            }).first else { continue }

            let anchor = Anchor(
                token: hit.token,
                text: hit.text,
                sectionName: hit.sectionName,
                stringFileOffset: hit.stringFileOffset,
                stringVMA: hit.stringVMA,
                matchVMA: hit.matchVMA,
                referenceFileOffset: reference.fileOffset,
                referenceVMA: reference.vma,
            )
            return try (anchor, findGate(in: data, text: text, anchor: anchor))
        }

        guard let found = firstFound else {
            throw PatcherError.patchSiteNotFound(
                "\(component): none of \(anchorTokens) appears in this binary's string sections",
            )
        }
        throw PatcherError.patchSiteNotFound(
            "\(component): \"\(found.text)\" is present but nothing in __TEXT,__text "
                + "forms its address (ADRP+ADD) — the boot-arg check looks compiled out",
        )
    }

    // MARK: - The gate

    /// The conditional branch that consumes the boot-arg lookup's result.
    ///
    /// Shape, in order: the first `bl` at or after the string xref, then the
    /// first conditional branch after that call. A `nop` reached before that
    /// branch is this patch's own output and ends the search — see the file
    /// header for why that matters.
    static func findGate(
        in data: Data,
        text: MachOSectionInfo,
        anchor: Anchor,
    ) throws -> Gate {
        let disassembler = ARM64Disassembler()
        let textEnd = Int(text.fileOffset) + Int(text.size)
        func decode(_ offset: Int) -> ARM64Instruction? {
            guard offset >= Int(text.fileOffset), offset + 4 <= textEnd else { return nil }
            return disassembler.disassembleOne(
                in: data,
                at: offset,
                address: text.address + UInt64(offset - Int(text.fileOffset)),
            )
        }

        var call: ARM64Instruction?
        for step in 0 ..< maxInstructionsToCall {
            guard let instruction = decode(anchor.referenceFileOffset + step * 4) else { break }
            // A direct `bl` only — the string is an argument to a call, and an
            // indirect `blr`/`blraa` through a register is not one this pass can
            // attribute a return value to.
            if instruction.mnemonic == "bl", branchTarget(of: instruction) != nil {
                call = instruction
                break
            }
        }

        let searchBase = call.map { Int($0.address - text.address) + Int(text.fileOffset) }
            ?? anchor.referenceFileOffset
        let window = call == nil ? maxFallbackInstructions : maxInstructionsAfterCall

        for step in 1 ... window {
            let offset = searchBase + step * 4
            guard let instruction = decode(offset) else { break }

            if instruction.mnemonic == "nop" {
                return Gate(
                    fileOffset: offset,
                    vma: instruction.address,
                    mnemonic: instruction.mnemonic,
                    operandString: instruction.operandString,
                    callFileOffset: call.map { Int($0.address - text.address) + Int(text.fileOffset) },
                    callVMA: call?.address,
                    targetVMA: nil,
                )
            }

            guard isConditionalBranch(instruction) else { continue }
            try validate(gate: instruction, in: data, text: text, after: call, disassembler)
            return Gate(
                fileOffset: offset,
                vma: instruction.address,
                mnemonic: instruction.mnemonic,
                operandString: instruction.operandString,
                callFileOffset: call.map { Int($0.address - text.address) + Int(text.fileOffset) },
                callVMA: call?.address,
                targetVMA: branchTarget(of: instruction),
            )
        }

        throw PatcherError.patchSiteNotFound(
            "\(component): no conditional branch within \(window) instructions of "
                + (call.map { "the call at 0x\(hex($0.address))" }
                    ?? "the \"\(anchor.text)\" xref at 0x\(hex(anchor.referenceVMA))"),
        )
    }

    /// Conditional branches, decided on the decoded mnemonic.
    static func isConditionalBranch(_ instruction: ARM64Instruction) -> Bool {
        switch instruction.mnemonic {
        case "cbz", "cbnz", "tbz", "tbnz": true
        default: instruction.mnemonic.hasPrefix("b.")
        }
    }

    /// Reject a branch that is not the gate.
    ///
    /// Two properties have to hold, and the Python checks neither: the branch
    /// tests the register the call returned in, and it jumps FORWARD, past the
    /// unsecure-cache path it guards. A branch that fails either is some other
    /// branch, and NOP'ing it would be a silent miscompile of a boot-critical
    /// binary — so this throws instead.
    static func validate(
        gate: ARM64Instruction,
        in data: Data,
        text: MachOSectionInfo,
        after call: ARM64Instruction?,
        _ disassembler: ARM64Disassembler,
    ) throws {
        if let target = branchTarget(of: gate) {
            let textEnd = text.address + text.size
            guard target > gate.address, target < textEnd else {
                throw PatcherError.patchSiteNotFound(
                    "\(component): branch at 0x\(hex(gate.address)) jumps to 0x\(hex(target)), "
                        + "which is not forward inside __TEXT,__text — not the unsecure-cache gate",
                )
            }
        }

        guard call != nil else { return } // Fallback path: nothing to attribute.

        switch gate.mnemonic {
        case "cbz", "cbnz", "tbz", "tbnz":
            let register = disassembler.firstRegisterName(gate)
            guard register == "x0" || register == "w0" else {
                throw PatcherError.patchSiteNotFound(
                    "\(component): branch at 0x\(hex(gate.address)) tests "
                        + "\(register ?? "an unknown register"), not the call's result in x0/w0",
                )
            }
        default:
            // `b.<cond>` reads the flags, so the call's result has to reach it
            // through a flag-setting instruction on x0/w0 in between.
            guard flagSetterOnResult(between: call!, and: gate, in: data, text: text, disassembler)
            else {
                throw PatcherError.patchSiteNotFound(
                    "\(component): \(gate.mnemonic) at 0x\(hex(gate.address)) is not preceded by a "
                        + "compare of the call's result — nothing ties it to the boot-arg lookup",
                )
            }
        }
    }

    /// Whether some instruction between the call and the branch sets the flags
    /// from x0/w0 — a `cmp`/`subs`/`ands`/`tst` reading register 0.
    static func flagSetterOnResult(
        between call: ARM64Instruction,
        and gate: ARM64Instruction,
        in data: Data,
        text: MachOSectionInfo,
        _ disassembler: ARM64Disassembler,
    ) -> Bool {
        var address = call.address + 4
        while address < gate.address {
            defer { address += 4 }
            let offset = Int(address - text.address) + Int(text.fileOffset)
            guard let instruction = disassembler.disassembleOne(in: data, at: offset, address: address),
                  instruction.detail?.updatesFlags == true,
                  let operands = instruction.detail?.operands
            else { continue }
            for operand in operands where operand.type == .register {
                let name = operand.reg.name
                if name == "x0" || name == "w0" {
                    return true
                }
            }
        }
        return false
    }

    /// The absolute address a branch jumps to, read from its last immediate
    /// operand, or `nil` when the instruction carries none.
    static func branchTarget(of instruction: ARM64Instruction) -> UInt64? {
        guard let operands = instruction.detail?.operands,
              let last = operands.last,
              last.type == .immediate,
              last.imm >= 0
        else { return nil }
        return UInt64(last.imm)
    }

    // MARK: - Recording

    private static func record(
        anchor: Anchor,
        gate: Gate,
        original: Data,
        patched: Data,
    ) -> PatchRecord {
        PatchRecord(
            patchID: patchID,
            component: component,
            fileOffset: gate.fileOffset,
            virtualAddress: gate.vma,
            originalBytes: original,
            patchedBytes: patched,
            beforeDisasm: disassemblyText(of: original, at: gate.vma),
            afterDisasm: disassemblyText(of: patched, at: gate.vma),
            // Worded as the Python words it, so a captured reference compares.
            description: "NOP the cache-validation branch gated on '\(anchor.token)'",
        )
    }

    // MARK: - Logging

    /// Five instructions around the gate, with the gate itself marked — the
    /// Python's `_log_asm` before/after block.
    private static func context(in data: Data, around gate: Gate, marking marker: Int) -> String {
        let disassembler = ARM64Disassembler()
        let start = max(gate.fileOffset - 8, 0)
        return (0 ..< 5).compactMap { step -> String? in
            let offset = start + step * 4
            guard offset + 4 <= data.count else { return nil }
            // The window starts two instructions BEFORE the gate, so the delta is
            // negative for the first steps. `UInt64(Int)` traps on a negative
            // value even under -O; wrap through the bit pattern instead.
            let vma = gate.vma &+ UInt64(bitPattern: Int64(offset - gate.fileOffset))
            guard let instruction = disassembler.disassembleOne(in: data, at: offset, address: vma)
            else { return nil }
            let tag = offset == marker ? " >>>" : "    "
            let mnemonic = instruction.mnemonic.count < 8
                ? instruction.mnemonic.padding(toLength: 8, withPad: " ", startingAt: 0)
                : instruction.mnemonic
            // Laid out by hand rather than with `String(format:)`: `%X` consumes
            // 32 bits, and every offset here is an `Int`.
            return "   \(tag) 0x\(hex(UInt64(offset), padTo: 8)): \(mnemonic) \(instruction.operandString)"
        }.joined(separator: "\n")
    }

    private static func disassemblyText(of bytes: Data, at vma: UInt64) -> String {
        ARM64Disassembler()
            .disassemble(bytes, at: vma)
            .map { $0.operandString.isEmpty ? $0.mnemonic : "\($0.mnemonic) \($0.operandString)" }
            .joined(separator: "; ")
    }

    // MARK: - Helpers

    /// Every 4-byte instruction offset in a section, in order.
    static func wordOffsets(of section: MachOSectionInfo) -> StrideTo<Int> {
        let start = Int(section.fileOffset)
        return stride(from: start, to: start + (Int(section.size) & ~3), by: 4)
    }

    private static func hex(_ value: UInt64, padTo width: Int = 0) -> String {
        let digits = String(value, radix: 16, uppercase: true)
        guard digits.count < width else { return digits }
        return String(repeating: "0", count: width - digits.count) + digits
    }
}