Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
21.4 KB
Raw Blame
// CustomFirmwareSeputil.swift — pin seputil's gigalocker file name to "AA".
//
// `seputil` keeps the SEP's "gigalocker" blob in a file named after the
// device's own UUID, built with a two-field format string:
//
//     snprintf(path, n, "%s/%s.gl", mountpoint, uuid);   // -> /mnt7/<uuid>.gl
//
// A vphone guest does not carry the UUID the gigalocker on the restored
// filesystem was written for, so seputil looks for a file that is not there.
// Rewriting the *uuid* field of that one literal to the constant `AA` makes
// every lookup resolve to `<mountpoint>/AA.gl`, which is the name the install
// gives the blob it ships. The mountpoint field is deliberately left as `%s`:
// it is chosen at runtime between `/mnt7` and `/private/xarts` and both must
// keep working.
//
// This is a data patch, not a code patch — the two bytes rewritten are ASCII
// inside `__TEXT,__cstring`, so no instruction is assembled here and the ARM64
// encoder has nothing to contribute. Capstone is used for the *anchor*: the
// literal has to be the one seputil actually formats with, which is proven by
// finding the `adr` or `adrp`/`add` reference in `__TEXT,__text` that materialises its
// address.
//
// Anchoring, in order, none of it positional:
//
//   1. `__TEXT,__cstring` from the load commands — a literal anywhere else is
//      not a C string this binary formats with.
//   2. The one whole NUL-terminated literal in that section shaped
//      `<dir>/<2-byte field>.gl`, where the field reads `%s` (pristine) or `AA`
//      (already patched). Whole-literal equality, so the tail of a longer
//      string cannot match.
//   3. An `adr` or `adrp`+`add` in `__TEXT,__text` computing that literal's VA, matched
//      on decoded operands.
//   4. The field to rewrite is the one after the literal's own last `/`.
//
// Port of `scripts/patchers/cfw_patch_seputil.py`, which stays the independent
// reference: `CustomFirmwareSeputilTests` runs the Python on one clone of a real seputil
// and this on another and compares the files byte for byte.
//
// Two deliberate differences from the reference, both of them narrowing:
//
//   * The Python searches the whole file for the *substring* `"/%s.gl\0"` and
//     patches the two bytes after the `/`. On this binary that substring is the
//     tail of `"%s/%s.gl"` and the result is the same byte, but the search is
//     not bounded to `__cstring`, does not require the match to be a whole
//     literal, and takes the first hit without checking that anything refers to
//     it. All three are tightened here.
//   * The Python leaves the code signature stale, because `cfw_install*.sh`
//     runs `ldid_sign` over the binary immediately afterwards. This
//     re-attests the page it dirtied through `CustomFirmwareMachOCodeSignature`, so the
//     binary that leaves this function verifies on its own. Pass
//     `reattest: false` to reproduce the reference's bytes exactly.

import Foundation
import VPhonePatchKit

public enum CustomFirmwareSeputil {
    // MARK: - Anchors

    /// Where the format string lives. A literal outside this section is not one
    /// the binary formats with, so the search never leaves it.
    public static let cstringSection = (segment: "__TEXT", section: "__cstring")

    /// Where a reference to the literal has to come from.
    public static let textSection = (segment: "__TEXT", section: "__text")

    /// The conversion the pristine literal uses for the gigalocker's name.
    public static let uuidConversion = "%s"

    /// What this patch pins that field to.
    public static let uuidReplacement = "AA"

    /// The suffix that makes a two-field format string a gigalocker path
    /// rather than any other path-shaped literal in the binary.
    public static let gigalockerSuffix = ".gl"

    /// How far past an `adrp` its `add` may sit. Eight instructions — the same
    /// window `KernelPatcherBase.findStringRefs` uses for the same job.
    static let addSearchWindow = 8

    /// One disassembler for the whole patcher; `ARM64Disassembler` is `Sendable`
    /// and stateless across calls.
    private static let disassembler = ARM64Disassembler()

    /// Default sink for the progress lines, matching the other patchers.
    public static let stderrLog: @Sendable (String) -> Void = { line in
        FileHandle.standardError.write(Data((line + "\n").utf8))
    }

    // MARK: - Site

    /// The literal this patch rewrites, and the field inside it.
    public struct Site: Sendable, Equatable {
        /// File offset of the literal's first byte.
        public let literalOffset: Int
        /// The literal's virtual address.
        public let literalVMA: UInt64
        /// The literal as it currently reads.
        public let literal: String
        /// File offset of the two-byte field after the literal's last `/`.
        public let fieldOffset: Int
        /// That field's virtual address.
        public let fieldVMA: UInt64
        /// True while the field still holds `%s`; false once it holds `AA`.
        public let isPristine: Bool

        /// The offsets the write dirties. Two, not one: a literal can straddle
        /// a page boundary, and then two slots need re-attesting.
        public var modifiedOffsets: [Int] {
            Array(fieldOffset ..< fieldOffset + CustomFirmwareSeputil.uuidReplacement.utf8.count)
        }
    }

    // MARK: - Outcome

    /// What one run did.
    public struct Outcome: Sendable {
        public enum Verdict: Sendable, Equatable, CustomStringConvertible {
            /// The field already reads `AA`. Nothing was written, nothing was
            /// re-attested — a second run over an installed binary lands here.
            case alreadyPatched
            /// A dry run that found a pristine field and stopped before writing.
            case wouldPatch
            /// The field was rewritten, and the page it sits in re-attested
            /// unless the caller asked otherwise.
            case patched

            public var description: String {
                switch self {
                case .alreadyPatched: "already patched"
                case .wouldPatch: "would patch"
                case .patched: "patched"
                }
            }
        }

        public let verdict: Verdict
        public let site: Site
        /// Addresses of the `add` instructions that materialise the literal.
        public let references: [UInt64]
        /// The record of the single write, on a run that wrote or would write.
        public let record: PatchRecord?
        /// Slot hashes re-attestation replaced. Empty when `reattest` was off.
        public let rehashes: [CustomFirmwareSlotRehash]

        public init(
            verdict: Verdict,
            site: Site,
            references: [UInt64],
            record: PatchRecord? = nil,
            rehashes: [CustomFirmwareSlotRehash] = [],
        ) {
            self.verdict = verdict
            self.site = site
            self.references = references
            self.record = record
            self.rehashes = rehashes
        }

        /// Sites this run put on disk — 1 on a live patch, 0 otherwise. Mirrors
        /// what `patch_seputil()` reports.
        public var sitesWritten: Int {
            verdict == .patched ? 1 : 0
        }
    }

    // MARK: - Entry points

    /// Patch the seputil binary at `url`.
    ///
    /// - Parameters:
    ///   - dryRun: locate and report, write nothing.
    ///   - reattest: recompute the slot hash of the page the write dirties.
    ///     On by default, so the binary verifies without an external re-sign.
    ///     Off reproduces `cfw_patch_seputil.py`'s bytes exactly.
    @discardableResult
    public static func patch(
        fileAt url: URL,
        dryRun: Bool = false,
        reattest: Bool = true,
        log: ((String) -> Void)? = stderrLog,
    ) throws -> Outcome {
        guard FileManager.default.fileExists(atPath: url.path) else {
            throw PatcherError.fileNotFound(url.path)
        }
        log?("  [.] \(url.path)")
        var data = try Data(contentsOfFileToRewrite: url)
        let outcome = try patch(&data, dryRun: dryRun, reattest: reattest, log: log)
        if outcome.verdict == .patched {
            try data.write(to: url)
        }
        return outcome
    }

    /// Patch an in-memory seputil image.
    @discardableResult
    public static func patch(
        _ data: inout Data,
        dryRun: Bool = false,
        reattest: Bool = true,
        log: ((String) -> Void)? = stderrLog,
    ) throws -> Outcome {
        if data.startIndex != 0 {
            data = Data(data)
        }

        let (cstring, text) = try sections(in: data)
        let site = try findSite(in: data, cstring: cstring)
        log?(
            "      [.] literal \"\(site.literal)\" @ 0x\(hex(site.literalVMA)) "
                + "(file 0x\(hex(site.literalOffset)))",
        )

        // The literal has to be one the code actually formats with. Without
        // this, a build that moved the gigalocker path into a different string
        // would still offer some `<dir>/%s.gl` to rewrite and the patch would
        // report success while changing nothing that runs.
        let references = references(to: site.literalVMA, in: data, text: text)
        guard !references.isEmpty else {
            throw PatcherError.patchSiteNotFound(
                "seputil: \"\(site.literal)\" @ 0x\(hex(site.literalVMA)) has no adr or adrp+add "
                    + "reference in \(textSection.segment),\(textSection.section); "
                    + "it is not the literal the gigalocker path is built from",
            )
        }
        log?("      [.] referenced from \(references.map { "0x" + hex($0) }.joined(separator: ", "))")

        guard site.isPristine else {
            log?(
                "      [=] field at 0x\(hex(site.fieldOffset)) already reads "
                    + "\"\(uuidReplacement)\"; nothing to patch/re-attest",
            )
            return Outcome(verdict: .alreadyPatched, site: site, references: references)
        }

        let replacement = Data(uuidReplacement.utf8)
        let range = site.fieldOffset ..< site.fieldOffset + replacement.count
        let original = Data(data[range])
        let record = record(for: site, original: original, replacement: replacement)

        guard !dryRun else {
            log?("      [+] would write \"\(uuidReplacement)\" at 0x\(hex(site.fieldOffset))")
            return Outcome(
                verdict: .wouldPatch,
                site: site,
                references: references,
                record: record,
            )
        }

        data.replaceSubrange(range, with: replacement)
        log?(
            "      [+] 0x\(hex(site.fieldOffset)): \(original.hex) -> \(replacement.hex) "
                + "(\"\(site.literal)\" -> \"\(patchedLiteral(of: site))\")",
        )

        var rehashes: [CustomFirmwareSlotRehash] = []
        if reattest {
            for directory in CustomFirmwareMachOCodeSignature.unsupportedCodeDirectories(in: data) {
                log?(
                    "      [-] CodeDirectory @ 0x\(hex(directory.offset)) is hashType "
                        + "\(directory.hashType), not SHA-256 — left untouched",
                )
            }
            rehashes = try CustomFirmwareMachOCodeSignature.reattest(&data, modifiedOffsets: site.modifiedOffsets)
            for rehash in rehashes {
                log?("      [+] \(rehash)")
            }
        }

        // Re-read the site the same way it was found, rather than trusting the
        // write: anything that moved underneath it shows up here.
        let after = try findSite(in: data, cstring: cstring)
        guard after.fieldOffset == site.fieldOffset, !after.isPristine else {
            throw PatcherError.patchVerificationFailed(
                "seputil: post-write read back \"\(after.literal)\" at 0x\(hex(after.fieldOffset))",
            )
        }
        log?("  [+] seputil gigalocker name pinned to \"\(uuidReplacement)\(gigalockerSuffix)\"")

        return Outcome(
            verdict: .patched,
            site: site,
            references: references,
            record: record,
            rehashes: rehashes,
        )
    }

    // MARK: - Reveal

    /// The two sections this patcher reads, from the load commands.
    static func sections(in data: Data) throws -> (cstring: MachOSectionInfo, text: MachOSectionInfo) {
        let all = MachOParser.parseSections(from: data)
        guard let cstring = all["\(cstringSection.segment),\(cstringSection.section)"] else {
            throw PatcherError.invalidFormat(
                "seputil: no \(cstringSection.segment),\(cstringSection.section) section "
                    + "(not a 64-bit Mach-O, or not the binary we were handed)",
            )
        }
        guard let text = all["\(textSection.segment),\(textSection.section)"] else {
            throw PatcherError.invalidFormat(
                "seputil: no \(textSection.segment),\(textSection.section) section",
            )
        }
        return (cstring, text)
    }

    /// The single gigalocker path literal in `__TEXT,__cstring`.
    ///
    /// Matching is on whole NUL-terminated literals, so `"%s.gl"` — the very
    /// next literal after the one we want on the reference binary — cannot be
    /// mistaken for it, and neither can the tail of any longer string.
    ///
    /// Throws when there is no candidate or more than one: with two, there is
    /// no evidence which one seputil formats with, and picking either is a
    /// coin flip that boots or does not.
    static func findSite(in data: Data, cstring: MachOSectionInfo) throws -> Site {
        let start = Int(cstring.fileOffset)
        let end = start + Int(cstring.size)
        guard start >= 0, end <= data.count, start <= end else {
            throw PatcherError.invalidFormat(
                "seputil: \(cstringSection.section) runs to 0x\(hex(end)), past the end of a "
                    + "0x\(hex(data.count))-byte file",
            )
        }

        var sites: [Site] = []
        var cursor = start
        while cursor < end {
            var terminator = cursor
            while terminator < end, data[terminator] != 0 {
                terminator += 1
            }
            guard terminator < end else { break } // unterminated tail, not a literal
            let literal = Array(data[cursor ..< terminator])
            if let field = fileField(of: literal), let pristine = pristineness(of: literal[field]) {
                sites.append(Site(
                    literalOffset: cursor,
                    literalVMA: cstring.address + UInt64(cursor - start),
                    literal: String(decoding: literal, as: UTF8.self),
                    fieldOffset: cursor + field.lowerBound,
                    fieldVMA: cstring.address + UInt64(cursor - start + field.lowerBound),
                    isPristine: pristine,
                ))
            }
            cursor = terminator + 1
        }

        guard let site = sites.first else {
            throw PatcherError.patchSiteNotFound(
                "seputil: no \"<dir>/\(uuidConversion)\(gigalockerSuffix)\" literal in "
                    + "\(cstringSection.segment),\(cstringSection.section)",
            )
        }
        guard sites.count == 1 else {
            throw PatcherError.patchSiteNotFound(
                "seputil: \(sites.count) gigalocker path literals "
                    + "(\(sites.map { "\"\($0.literal)\" @ 0x" + hex($0.literalOffset) }.joined(separator: ", "))); "
                    + "refusing to guess which one builds the path",
            )
        }
        return site
    }

    /// The range, within `literal`, of the field after its last `/`.
    ///
    /// `"%s/%s.gl"` names a directory and a file. The field this patch pins is
    /// the file's, so it is read off the literal's own last separator instead
    /// of being counted in from either end.
    static func fileField(of literal: [UInt8]) -> Range<Int>? {
        let suffix = Array(gigalockerSuffix.utf8)
        let width = uuidReplacement.utf8.count
        guard literal.count > suffix.count,
              literal.suffix(suffix.count).elementsEqual(suffix),
              let slash = literal.lastIndex(of: UInt8(ascii: "/"))
        else { return nil }
        let fieldStart = slash + 1
        let fieldEnd = literal.count - suffix.count
        guard fieldEnd - fieldStart == width else { return nil }
        return fieldStart ..< fieldEnd
    }

    /// `true` for a field that still reads `%s`, `false` for one already
    /// reading `AA`, `nil` for anything else — which is not this patch's site.
    static func pristineness(of field: ArraySlice<UInt8>) -> Bool? {
        if field.elementsEqual(uuidConversion.utf8) {
            return true
        }
        if field.elementsEqual(uuidReplacement.utf8) {
            return false
        }
        return nil
    }

    /// Addresses of the `add` instructions that, with their `adrp`, materialise
    /// `vma` somewhere in `__TEXT,__text`.
    ///
    /// Pairing is the same shape `KernelPatcherBase.findStringRefs` uses, but
    /// read off Capstone's decoded operands rather than raw encodings: an
    /// `adrp` whose immediate is the literal's page, then an `add` within the
    /// window whose source register is that `adrp`'s destination and whose
    /// immediate is the literal's page offset.
    static func references(to vma: UInt64, in data: Data, text: MachOSectionInfo) -> [UInt64] {
        let start = Int(text.fileOffset)
        let size = Int(text.size)
        guard start >= 0, size > 0, start + size <= data.count else { return [] }
        let instructions = disassembler.disassemble(Data(data[start ..< start + size]), at: text.address)

        let page = vma & ~0xFFF
        let pageOffset = Int64(vma & 0xFFF)

        var sites: [UInt64] = []
        for (index, insn) in instructions.enumerated() {
            // iOS 17 uses ADR for the same whole format literal.
            if insn.mnemonic == "adr", let operands = insn.detail?.operands,
               operands.count == 2, operands[0].type == .register,
               operands[1].type == .immediate, UInt64(bitPattern: operands[1].imm) == vma {
                sites.append(insn.address)
                continue
            }
            guard insn.mnemonic == "adrp",
                  let operands = insn.detail?.operands,
                  operands.count == 2,
                  operands[0].type == .register,
                  operands[1].type == .immediate,
                  UInt64(bitPattern: operands[1].imm) == page
            else { continue }

            let base = operands[0].reg.rawValue
            let limit = Swift.min(index + addSearchWindow, instructions.count - 1)
            var cursor = index + 1
            while cursor <= limit {
                let candidate = instructions[cursor]
                cursor += 1
                guard candidate.mnemonic == "add",
                      let addOperands = candidate.detail?.operands,
                      addOperands.count == 3,
                      addOperands[0].type == .register,
                      addOperands[1].type == .register,
                      addOperands[1].reg.rawValue == base,
                      addOperands[2].type == .immediate,
                      addOperands[2].imm == pageOffset,
                      !isShiftedAddImmediate(candidate)
                else { continue }
                sites.append(candidate.address)
                break
            }
        }
        return sites
    }

    /// True when an `add` immediate carries `lsl #12`.
    ///
    /// PatchKit's decoded operands do not surface an operand's shift, so the
    /// `sh` field is read off the instruction's own 32-bit encoding — still a
    /// property of the decode, never of the printed operand text. Without it an
    /// `add xD, xN, #imm, lsl #12` could be paired as if it computed
    /// `page + imm`, which is a different address than it really forms.
    static func isShiftedAddImmediate(_ insn: ARM64Instruction) -> Bool {
        guard insn.bytes.count == 4 else { return false }
        let word = UInt32(insn.bytes[0])
            | UInt32(insn.bytes[1]) << 8
            | UInt32(insn.bytes[2]) << 16
            | UInt32(insn.bytes[3]) << 24
        return (word >> 22) & 1 == 1
    }

    // MARK: - Reporting

    /// How the literal reads once the field is rewritten.
    static func patchedLiteral(of site: Site) -> String {
        var literal = Array(site.literal.utf8)
        guard let field = fileField(of: literal) else { return site.literal }
        literal.replaceSubrange(field, with: Array(uuidReplacement.utf8))
        return String(decoding: literal, as: UTF8.self)
    }

    /// The record for the one write, with the reference's own `patchID`,
    /// `component` and wording so a captured reference compares field for
    /// field.
    private static func record(for site: Site, original: Data, replacement: Data) -> PatchRecord {
        PatchRecord(
            patchID: "system-seputil-boot-gigalocker_uuid",
            component: "seputil",
            fileOffset: site.fieldOffset,
            virtualAddress: site.fieldVMA,
            originalBytes: original,
            patchedBytes: replacement,
            description: "gigalocker path format '/\(uuidConversion)\(gigalockerSuffix)' "
                + "-> '/\(uuidReplacement)\(gigalockerSuffix)'",
        )
    }

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

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