Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
20.9 KB
Raw Blame
// CustomFirmwareDiskImage.swift — force diskimagesiod's DDI mount-completion gate open.
//
// Swift port of `scripts/patchers/cfw_patch_diskimagesiod.py`, driven by
// `cfw.py patch-diskimagesiod <binary>` and, in the shipped installers, by
// `scripts/cfw_install.sh:415` / `cfw-kit/lib/base_stages.sh:188`.
//
// Why the patch exists
// ────────────────────
// `pymobiledevice3 mounter auto-mount` attaches the personalized DDI, then
// MobileStorageMounter waits on diskimagesiod's
// `-[DIDiskArb waitForDAMountWithExpectedCount:diskTracker:]` before it
// performs the real (nobrowse) mount of the DDI volume at /System/Developer.
// That wait spins until `isMountComplete` returns YES, which is
// `callbackReached || (appearedDiskCount >= expectedCount &&
// mountedDiskCount >= mountableDiskCount)`. On the iOS-27-userland /
// 26.4-vphone600-kernel hybrid it never becomes true: only some of the DMG's
// IOMedia ever "appear" to diskimagesiod's DiskArbitration session, and
// diskarbitrationd never auto-mounts the volume, so the wait hangs forever and
// pmd3 times out. diskimagesiod itself does NOT mount the DDI — its
// `-[DIDiskArb mountWithDeviceName:…]` is dead code; it only gates
// MobileStorageMounter. Forcing `isMountComplete` to YES lets the wait return
// immediately so MobileStorageMounter proceeds and mounts the DDI.
//
// Pairs with the JB kernel patches that make the DDI attachable and mountable
// (the DiskImages2 ABI pokes, and the Sandbox `mpo_proc_check_syscall_unix`
// stub that lets MobileStorageMounter's `mount_apfs` issue `mount(2)`).
// No-op-in-effect on version-matched userlands, where the wait completes on its
// own and returning YES early changes nothing observable.
//
// How the site is found
// ─────────────────────
// Nothing here is a hardcoded offset. Two source-backed anchors, in order:
//
//   1. `LC_SYMTAB`: a symbol whose name contains `isMountCompleteWithExpectedCount`.
//      Shipped diskimagesiod is stripped, so this normally misses — it is kept
//      because it is the cheapest and most direct anchor when it does hit.
//   2. ObjC runtime metadata, which survives stripping:
//      selector cstring in `__TEXT,__objc_methname`
//        → its `__objc_selrefs` entry (chained-fixup aware)
//        → the relative method-list entry naming it
//        → that entry's `imp` field, relative-addressed.
//      `__TEXT,__objc_methlist` is walked *structurally* first — a packed run
//      of `{entsizeAndFlags, count}` headers followed by `count` 12-byte
//      `{name, types, imp}` entries, each list 8-byte aligned. The structural
//      walk cannot land mid-entry and cannot mistake a `__const` word for a
//      method. The Python's 4-byte-strided scan is kept behind it, over the
//      same sections the Python tries plus `__objc_methlist` itself, so this
//      port is never less capable than the one it replaces. Either way the
//      result is required to be the *only* entry in the image naming that
//      selector.
//
// The resolved IMP is then checked to land inside `__TEXT,__text` and to decode
// as real instructions before a single byte is written.
//
// What is written
// ───────────────
// `mov x0, #1 ; ret` over the method prologue. Safe: the function returns to the
// caller's (unsigned) LR without ever having pushed a frame, so overwriting
// `pacibsp; stp …` loses nothing that the new epilogue needs. Both words come
// from the encoder — `ARM64Encoder.encodeMovzX` builds MOVZ from its ISA fields
// and `ARM64.ret` is the keystone-derived constant; `CustomFirmwareDiskImageTests`
// asserts the two agree with `ARM64.movX0_1`.
//
// Re-signing
// ──────────
// Off by default, matching the Python and the call site: `cfw_install.sh`
// re-signs the patched binary with `ldid` under the extracted
// `com.apple.diskimagesiod` entitlements, so a slot re-attest here would be
// overwritten moments later. `reattest: true` recomputes the CodeDirectory slot
// hashes through `CustomFirmwareMachOCodeSignature` instead, which is what a caller that
// drops the `ldid` step needs — and what makes `codesign -v` pass on the patched
// file on its own.

import Foundation
import VPhonePatchKit

/// Forces `-[DIDiskArb isMountCompleteWithExpectedCount:diskTracker:]` to
/// return YES so MobileStorageMounter stops waiting on a mount that will never
/// be reported.
public enum CustomFirmwareDiskImage {
    // MARK: - Identity

    /// The component name the Python records this write under.
    public static let component = "diskimagesiod"

    /// The selector whose implementation is stubbed.
    public static let selector = "isMountCompleteWithExpectedCount:diskTracker:"

    /// The `LC_SYMTAB` fragment strategy 1 looks for. Deliberately shorter than
    /// the selector: a symbol name is `-[DIDiskArb isMountComplete…]`, and the
    /// colon-bearing tail differs between symbol spellings.
    public static let symbolFragment = "isMountCompleteWithExpectedCount"

    /// The method, as it reads in a disassembler.
    public static let method = "-[DIDiskArb \(selector)]"

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

    /// `mov x0, #1 ; ret`.
    ///
    /// MOVZ is built from its ISA fields by ``ARM64Encoder/encodeMovzX(rd:imm16:shift:)``;
    /// the `?? ARM64.movX0_1` arm is unreachable (that encoder returns `nil`
    /// only for a shift above 48) and exists so this stays a plain `let` with
    /// no trap in it. `CustomFirmwareDiskImageTests` asserts the two spellings are the
    /// same four bytes.
    public static let replacement: Data =
        (ARM64Encoder.encodeMovzX(rd: 0, imm16: 1) ?? ARM64.movX0_1) + ARM64.ret

    // MARK: - Results

    /// Which anchor found the implementation.
    public enum Anchor: String, Sendable, Equatable {
        /// `LC_SYMTAB` carried the symbol. Only on an unstripped build.
        case symbolTable
        /// Structural walk of `__TEXT,__objc_methlist`.
        case relativeMethodList
        /// The Python's strategy: a 4-byte-strided scan, over `__objc_methlist`
        /// when the structural walk could not follow it, then over the
        /// `__objc_const` sections of the pre-`__objc_methlist` layout.
        case methodListScan
    }

    /// The implementation this patch overwrites.
    public struct Site: Sendable, Equatable {
        /// File offset of the method's first instruction.
        public let fileOffset: Int
        /// Its virtual address, when an anchor produced one.
        public let virtualAddress: UInt64?
        /// How it was found.
        public let anchor: Anchor
        /// The bytes the patch replaces, as found — ``replacement``-many.
        public let original: Data

        /// True when the site already holds this patch's own output.
        public var isAlreadyPatched: Bool {
            original == CustomFirmwareDiskImage.replacement
        }
    }

    /// What a run did.
    public enum Outcome: String, Sendable, Equatable {
        /// The prologue already read `mov x0, #1 ; ret`; nothing was written
        /// there. (A stale slot hash may still have been re-attested.)
        case alreadyPatched
        /// `dryRun` was set, so the site was located and reported only.
        case wouldPatch
        /// The prologue was replaced.
        case patched
    }

    /// The outcome of one run, and the site it acted on.
    public struct Report: Sendable {
        public let outcome: Outcome
        public let site: Site
        /// The write, in the shape the Python's reference capture records it.
        /// `nil` unless the prologue bytes actually changed.
        public let record: PatchRecord?
        /// CodeDirectory slots re-attested. Empty unless `reattest` was set,
        /// and empty on a second run because the stored hashes already match.
        public let rehashes: [CustomFirmwareSlotRehash]

        /// The parity number: the Python writes exactly one site, and so must this.
        public var sitesWritten: Int {
            record == nil ? 0 : 1
        }
    }

    /// 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

    /// Stub the mount-completion gate in `data`.
    ///
    /// Idempotent: a buffer that already reads `mov x0, #1 ; ret` at the site
    /// reports ``Outcome/alreadyPatched`` and writes nothing, rather than
    /// failing to recognise a prologue that is no longer there. Re-running is
    /// the normal case — `cfw install` is re-run against an already-installed
    /// volume all the time — and commit `8eb6c8b` exists because a sibling
    /// patcher got this wrong.
    ///
    /// - Parameters:
    ///   - reattest: recompute the CodeDirectory slot hashes for the pages the
    ///     write touched. Off by default; see the file header for why.
    ///   - dryRun: locate and report without writing.
    /// - Throws: ``PatcherError/invalidFormat(_:)`` when the buffer is not a
    ///   64-bit Mach-O or its ObjC metadata is ambiguous, and
    ///   ``PatcherError/patchSiteNotFound(_:)`` when no anchor resolves — both
    ///   have to stop the install rather than be guessed at.
    @discardableResult
    public static func patch(
        _ data: inout Data,
        reattest: Bool = false,
        dryRun: Bool = false,
        log: ((String) -> Void)? = stdoutLog,
    ) throws -> Report {
        if data.startIndex != 0 {
            data = Data(data)
        }

        let site = try locate(in: data)
        let patched = replacement
        log?("  \(method) @ \(describe(site))")
        log?("  Before: \(disassemblyText(of: site.original, at: site.virtualAddress))")

        guard !dryRun else {
            log?("  [.] dry-run: would write \(patched.hex) at 0x\(hex(UInt64(site.fileOffset)))")
            return Report(outcome: .wouldPatch, site: site, record: nil, rehashes: [])
        }

        var record: PatchRecord?
        if site.isAlreadyPatched {
            log?("  [=] already `mov x0, #1 ; ret` at 0x\(hex(UInt64(site.fileOffset))); nothing to write")
        } else {
            data.replaceSubrange(site.fileOffset ..< site.fileOffset + patched.count, with: patched)
            record = makeRecord(site: site, patched: patched)
            log?("  After:  \(disassemblyText(of: patched, at: site.virtualAddress))")
        }

        var rehashes: [CustomFirmwareSlotRehash] = []
        if reattest {
            // First and last byte of the write: an 8-byte span sits inside one
            // 4 KiB page here, but a page boundary between them would otherwise
            // leave the second page's slot stale.
            rehashes = try CustomFirmwareMachOCodeSignature.reattest(
                &data,
                modifiedOffsets: [site.fileOffset, site.fileOffset + patched.count - 1],
            )
            for rehash in rehashes {
                log?("      [~] \(rehash)")
            }
            if rehashes.isEmpty {
                log?("  [=] code directory slots already current; no re-attest needed")
            }
        }

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

        log?("  [+] \(method) forced to YES at 0x\(hex(UInt64(site.fileOffset)))")
        return Report(
            outcome: site.isAlreadyPatched ? .alreadyPatched : .patched,
            site: site,
            record: record,
            rehashes: rehashes,
        )
    }

    /// File-backed form of ``patch(_:reattest:dryRun:log:)``.
    ///
    /// The file is rewritten only when its bytes actually changed, so a
    /// re-run leaves even the modification time alone.
    @discardableResult
    public static func patch(
        fileAt url: URL,
        reattest: Bool = false,
        dryRun: 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, reattest: reattest, dryRun: dryRun, log: log)
        if !dryRun, report.record != nil || !report.rehashes.isEmpty {
            try data.write(to: url)
        }
        return report
    }

    // MARK: - Locating the implementation

    /// Resolve the method's first instruction without touching the buffer.
    ///
    /// - Throws: ``PatcherError/patchSiteNotFound(_:)`` when every anchor is
    ///   exhausted, ``PatcherError/invalidFormat(_:)`` when the image is not a
    ///   64-bit Mach-O or names the selector from more than one implementation.
    public static func locate(in data: Data) throws -> Site {
        let data = rebased(data)
        guard data.count > 32, data.loadLE(UInt32.self, at: 0) == machMagic64 else {
            throw PatcherError.invalidFormat("\(component): not a 64-bit Mach-O")
        }
        let segments = MachOParser.parseSegments(from: data)
        let sections = MachOParser.parseSections(from: data)
        let textRange = sections[textSectionKey].map {
            Int($0.fileOffset) ..< Int($0.fileOffset) + Int($0.size)
        }

        // Strategy 1 — the symbol table, when the image kept one.
        if let va = MachOParser.findSymbol(containing: symbolFragment, in: data),
           let offset = MachOParser.vaToFileOffset(va, segments: segments),
           let site = makeSite(
               in: data,
               fileOffset: offset,
               virtualAddress: va,
               anchor: .symbolTable,
               textRange: textRange,
           )
        {
            return site
        }

        // Strategy 2 — ObjC metadata, which survives stripping.
        let (impVA, anchor) = try resolveIMPViaObjCMetadata(in: data, sections: sections)
        guard let offset = MachOParser.vaToFileOffset(impVA, segments: segments) else {
            throw PatcherError.invalidFormat(
                "\(method): IMP va 0x\(hex(impVA)) is in no mapped segment",
            )
        }
        guard let site = makeSite(
            in: data,
            fileOffset: offset,
            virtualAddress: impVA,
            anchor: anchor,
            textRange: textRange,
        ) else {
            throw PatcherError.patchSiteNotFound(
                "\(method): IMP at 0x\(hex(impVA)) (foff 0x\(hex(UInt64(offset)))) "
                    + "is outside __TEXT,__text or does not decode as instructions",
            )
        }
        return site
    }

    /// Build a ``Site`` when the candidate offset survives validation, else nil.
    ///
    /// Two checks, both semantic rather than positional: the offset must lie in
    /// the image's executable section, and the words there must decode — unless
    /// they are already this patch's own output, which is the idempotent case.
    static func makeSite(
        in data: Data,
        fileOffset: Int,
        virtualAddress: UInt64?,
        anchor: Anchor,
        textRange: Range<Int>?,
    ) -> Site? {
        let length = replacement.count
        guard fileOffset >= 0, fileOffset + length <= data.count else { return nil }
        if let textRange, !(textRange.contains(fileOffset) && textRange.contains(fileOffset + length - 1)) {
            return nil
        }

        let original = Data(data[fileOffset ..< fileOffset + length])
        let site = Site(
            fileOffset: fileOffset,
            virtualAddress: virtualAddress,
            anchor: anchor,
            original: original,
        )
        if site.isAlreadyPatched {
            return site
        }

        // `skipData` is on in the shared disassembler, so an undecodable word
        // arrives as a data pseudo-instruction (id 0) instead of ending the
        // stream — which is what makes this a usable "is this code?" test.
        let decoded = ARM64Disassembler().disassemble(
            original,
            at: virtualAddress ?? UInt64(fileOffset),
        )
        guard decoded.count == length / 4, decoded.allSatisfy(\.isDecoded) else { return nil }
        return site
    }

    // MARK: - Recording

    private static func makeRecord(site: Site, patched: Data) -> PatchRecord {
        PatchRecord(
            patchID: patchID,
            component: component,
            fileOffset: site.fileOffset,
            virtualAddress: site.virtualAddress,
            originalBytes: site.original,
            patchedBytes: patched,
            beforeDisasm: disassemblyText(of: site.original, at: site.virtualAddress),
            afterDisasm: disassemblyText(of: patched, at: site.virtualAddress),
            description: "\(method) -> mov x0, #1; ret",
        )
    }

    // MARK: - Section helpers

    static let machMagic64: UInt32 = 0xFEED_FACF

    /// Executable section every anchor's answer has to land in.
    static let textSectionKey = "__TEXT,__text"

    /// Where modern toolchains put packed relative method lists.
    static let methodListSectionKey = "__TEXT,__objc_methlist"

    /// Sections the strided fallback scan walks, in order: the packed method
    /// lists again, then the older layouts where method lists sit inside
    /// `class_ro_t` records. The Python's list, plus `__objc_methlist`.
    static let scannedSectionKeys = [
        methodListSectionKey,
        "__DATA_CONST,__objc_const",
        "__DATA,__objc_const",
        "__AUTH_CONST,__objc_const",
    ]

    /// Selector cstrings live in the first of these that the image has.
    static let stringSectionKeys = ["__TEXT,__objc_methname", "__TEXT,__cstring"]

    /// `{uint32 entsizeAndFlags, uint32 count}`.
    static let methodListHeaderSize = 8
    /// Lists are laid out back to back on an 8-byte boundary.
    static let methodListAlignment = 8
    /// `entsizeAndFlags` bit 31 — entries are relative, not pointers.
    static let relativeMethodListFlag: UInt32 = 0x8000_0000
    /// The entry-size field, with the flag bits masked off.
    static let methodListEntrySizeMask: UInt32 = 0xFFFC
    /// `{int32 name, int32 types, int32 imp}`.
    static let relativeMethodEntrySize = 12
    /// `DYLD_CHAINED_PTR_64` rebase: `target` is the low 36 bits.
    static let chainedRebaseTargetMask: UInt64 = 0x0000_000F_FFFF_FFFF

    static func section(_ sections: [String: MachOSectionInfo], _ keys: String...) -> MachOSectionInfo? {
        for key in keys {
            if let section = sections[key] {
                return section
            }
        }
        return nil
    }

    /// The image's preferred load address: the `__TEXT` segment's `vmaddr`,
    /// read off the section table so no extra segment walk is needed.
    static func imageBase(_ sections: [String: MachOSectionInfo]) -> UInt64 {
        sections[textSectionKey].map { $0.address - UInt64($0.fileOffset) } ?? 0
    }

    /// Map a file offset back to a virtual address through the section table.
    ///
    /// Zero-fill sections (`__bss`, `__common`) carry a file offset of 0 and
    /// would otherwise claim the Mach-O header, so they are skipped. The
    /// candidates are walked in file order rather than in the dictionary's,
    /// which has no defined order — two runs over the same bytes must resolve
    /// the same address.
    static func virtualAddress(ofFileOffset offset: Int, sections: [String: MachOSectionInfo]) -> UInt64? {
        for section in sections.values.sorted(by: { $0.fileOffset < $1.fileOffset }) {
            let start = Int(section.fileOffset)
            guard start > 0 else { continue }
            if offset >= start, offset < start + Int(section.size) {
                return section.address + UInt64(offset - start)
            }
        }
        return nil
    }

    // MARK: - Formatting

    static func describe(_ site: Site) -> String {
        let va = site.virtualAddress.map { " va 0x\(hex($0))" } ?? ""
        return "foff 0x\(hex(UInt64(site.fileOffset)))\(va) [\(site.anchor.rawValue)]"
    }

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

    static func hex(_ value: UInt64) -> String {
        String(value, radix: 16, uppercase: true)
    }

    static func alignUp(_ value: Int, to alignment: Int) -> Int {
        (value + alignment - 1) & ~(alignment - 1)
    }

    /// Zero-base a `Data` so the integer subscripts used throughout are valid.
    static func rebased(_ data: Data) -> Data {
        data.startIndex == 0 ? data : Data(data)
    }
}