Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
21.4 KB
Raw Blame
// DyldSharedCacheCodeSignature.swift — Page-hash re-signing for dyld shared cache chunks.
//
// Why this exists
// ---------------
// On iPhone17,3 / iOS 26+ the kernel runs with `codeSigningMonitor == 2`: it
// hands per-page hash validation to TXM, and TXM holds the slot hashes the
// cache was registered with. So a byte changed inside an executable mapping
// does not fail at patch time, or at boot; it fails the first time that 16 KiB
// page is demand-paged in, as a `KERN_PROTECTION_FAILURE` / SIGKILL on
// whichever process touched it. Every DSC edit has to be followed by re-hashing
// the affected page's slot, or the guest panics on a page fault nobody can
// trace back to the patch.
//
// This is the DSC path and it is not the Mach-O path
// --------------------------------------------------
// The two must not share an implementation. Here:
//
//   * the signature is found through the chunk header's
//     `codeSignatureOffset` @0x28 / `codeSignatureSize` @0x30 — a DSC image
//     carries no `LC_CODE_SIGNATURE` of its own, only the chunk-level one
//   * pages are 16 KiB (`pageSize` log2 == 14), not 4 KiB
//   * there is a single code directory, no alternate SHA-1 CD to skip past
//   * chunks are page-aligned, so `nCodeSlots * pageSize == codeLimit` and
//     there is no short tail slot. The independent Mach-O path does have one,
//     and getting it wrong is what regressed re-signing once already.
//
// Side effect, by design
// ----------------------
// Rewriting slot hashes changes the code directory's contents and therefore its
// cdHash. That is only survivable because the CFW kernel patch
// `patch_amfi_cdhash_in_trustcache` — `KernelCustomFirmwarePatchAmfiTrustcache` in this
// repo — short-circuits AMFI's per-image trust-cache lookup to return 1. This
// file must not be used on a firmware that does not carry that patch.
//
// Port of `scripts/patchers/cfw_dsc_codesign.py`, which stays the independent
// reference for the slot hashes computed here.
//
// It is not a port of how the reference chooses *which* pages to hash. The
// Python takes bare addresses and hashes one page each, so a write that crosses
// a 16 KiB boundary leaves the following page's slot stale and still reports
// success — reproduced on the 24A435 cache with an 8-byte write at
// 0x22AC0FFFC, which dirties pages 2563 and 2564 and gets 2563 re-signed. The
// six sites `cfw_patch_camera_dsc.py` writes miss that by 1072 bytes, so the
// reference is safe by margin rather than by construction. Here the page set is
// derived from the spans that were actually written, and `DyldSharedCacheChunkSet` records
// those itself.

import CryptoKit
import Foundation
import VPhonePatchKit

/// The `CS_CodeDirectory` of one chunk, reduced to what re-signing needs.
public struct DyldSharedCacheChunkCodeDirectory: Sendable {
    /// Offset of the CD blob within the chunk file.
    public let blobOffset: Int
    /// Byte length of the CD blob.
    public let blobLength: Int
    /// Offset of slot 0 within the CD blob.
    public let hashOffset: Int
    /// Bytes per slot — 32 for SHA-256.
    public let hashSize: Int
    /// Number of code slots.
    public let codeSlotCount: Int
    /// Chunk byte range the signature covers.
    public let codeLimit: Int
    /// Bytes per slot's page — 16384 on this cache.
    public let pageSize: Int

    /// Chunk-file offset of slot `index`'s hash.
    public func slotOffset(forPage index: Int) -> Int {
        blobOffset + hashOffset + index * hashSize
    }
}

/// One slot rewritten, for logging and for cross-checking against the Python.
public struct DyldSharedCacheSlotReattestation: Sendable {
    public let chunkURL: URL
    public let pageIndex: Int
    /// Offset of the page's first byte in the chunk file.
    public let chunkOffset: Int
    /// Offset of the slot hash in the chunk file.
    public let slotOffset: Int
    public let hashBefore: Data
    public let hashAfter: Data
}

/// One page of one chunk.
public struct DyldSharedCachePageReference: Sendable, Hashable {
    public let chunkURL: URL
    public let pageIndex: Int
}

/// A page that re-attestation could not cover, and why.
///
/// Every one of these used to be an early `continue` that produced no record
/// and, under the default `log: nil`, no output either — so "I skipped it" came
/// back looking exactly like "there was nothing to do". The Python reference
/// prints each one, and so does this, but the caller also gets them as values
/// rather than as text it would have to have been listening for.
public struct DyldSharedCacheReattestationSkip: Sendable {
    public enum Reason: Sendable, CustomStringConvertible {
        case addressNotMapped(vma: UInt64)
        case spanNotAddressable(vma: UInt64, length: Int)
        case chunkHasNoCodeDirectory(chunk: String)
        case pageBeyondCodeSlots(chunk: String, page: Int, codeSlotCount: Int)
        case pageBeyondCodeLimit(chunk: String, page: Int, codeLimit: Int)
        case shortPageRead(chunk: String, page: Int, got: Int, wanted: Int)

        public var description: String {
            switch self {
            case let .addressNotMapped(vma):
                "vma 0x\(String(vma, radix: 16, uppercase: true)) not mapped in any chunk"
            case let .spanNotAddressable(vma, length):
                "span at vma 0x\(String(vma, radix: 16, uppercase: true)) length \(length) "
                    + "runs past the end of its chunk"
            case let .chunkHasNoCodeDirectory(chunk):
                "chunk \(chunk) has no recognised CS_SuperBlob/CD"
            case let .pageBeyondCodeSlots(chunk, page, codeSlotCount):
                "page \(page) of \(chunk) is past nCodeSlots (\(codeSlotCount))"
            case let .pageBeyondCodeLimit(chunk, page, codeLimit):
                "page \(page) of \(chunk) overruns codeLimit "
                    + "(0x\(String(codeLimit, radix: 16, uppercase: true)))"
            case let .shortPageRead(chunk, page, got, wanted):
                "short read at page \(page) of \(chunk) (got \(got) of \(wanted))"
            }
        }
    }

    public let reason: Reason
    public var description: String {
        reason.description
    }
}

/// What one re-attestation run did.
///
/// Three outcomes that used to share the empty array are separate here: no
/// pages were eligible, every page already matched, and some pages were
/// skipped. A caller that wants "the patch is fully covered" should check
/// `isFullyAttested`.
public struct DyldSharedCacheReattestation: Sendable {
    /// Slots whose stored hash was changed (or, on a dry run, would have been).
    public let updated: [DyldSharedCacheSlotReattestation]
    /// Pages whose stored slot already matched what the page hashes to.
    public let alreadyAttested: [DyldSharedCachePageReference]
    /// Pages that could not be covered at all.
    public let skipped: [DyldSharedCacheReattestationSkip]

    /// Pages the run actually reached — rewritten plus already-correct.
    public var pagesAttested: Int {
        updated.count + alreadyAttested.count
    }

    /// True when every page the caller's spans touched now carries a slot hash
    /// that matches its contents. False the moment anything was skipped.
    public var isFullyAttested: Bool {
        skipped.isEmpty
    }

    public var summary: String {
        "\(updated.count) slot(s) rewritten, \(alreadyAttested.count) already correct, "
            + "\(skipped.count) skipped"
    }
}

public enum DyldSharedCacheCodeSignature {
    static let superBlobMagic: UInt32 = 0xFADE_0CC0
    static let codeDirectoryMagic: UInt32 = 0xFADE_0C02
    static let codeDirectorySlot: UInt32 = 0
    static let hashTypeSHA256: UInt8 = 2

    // MARK: - Reading the chunk's code directory

    /// Locate a chunk's `CS_CodeDirectory`.
    ///
    /// Returns `nil` — rather than throwing — when the chunk simply has no
    /// signature to update. Several chunks in a cache are like that, and a
    /// patch that lands in one of them is not an error.
    public static func readCodeDirectory(ofChunk url: URL) throws -> DyldSharedCacheChunkCodeDirectory? {
        let head = try DyldSharedCacheChunkSet.read(url: url, offset: 0, length: 0x100)
        guard head.count >= 0x38, head.prefix(5) == Data("dyld_".utf8) else { return nil }

        let signatureOffset = head.loadLE(UInt64.self, at: 0x28)
        let signatureSize = head.loadLE(UInt64.self, at: 0x30)
        guard signatureOffset != 0, signatureSize != 0 else { return nil }

        // CS_SuperBlob, big-endian.
        let superHead = try DyldSharedCacheChunkSet.read(url: url, offset: signatureOffset, length: 12)
        guard superHead.count == 12 else { return nil }
        guard superHead.loadBE(UInt32.self, at: 0) == superBlobMagic else { return nil }
        let superLength = superHead.loadBE(UInt32.self, at: 4)
        let blobCount = superHead.loadBE(UInt32.self, at: 8)
        guard UInt64(superLength) <= signatureSize, blobCount <= 256 else { return nil }

        let indexData = try DyldSharedCacheChunkSet.read(
            url: url,
            offset: signatureOffset + 12,
            length: Int(blobCount) * 8,
        )
        guard indexData.count == Int(blobCount) * 8 else { return nil }

        var directoryOffsetInSuperBlob: UInt32?
        for index in 0 ..< Int(blobCount) {
            let slotType = indexData.loadBE(UInt32.self, at: index * 8)
            if slotType == codeDirectorySlot {
                directoryOffsetInSuperBlob = indexData.loadBE(UInt32.self, at: index * 8 + 4)
                break
            }
        }
        guard let directoryOffsetInSuperBlob else { return nil }
        let blobOffset = signatureOffset + UInt64(directoryOffsetInSuperBlob)

        // CS_CodeDirectory, big-endian.
        let directoryHead = try DyldSharedCacheChunkSet.read(url: url, offset: blobOffset, length: 44)
        guard directoryHead.count == 44 else { return nil }
        guard directoryHead.loadBE(UInt32.self, at: 0) == codeDirectoryMagic else { return nil }

        let blobLength = Int(directoryHead.loadBE(UInt32.self, at: 4))
        let hashOffset = Int(directoryHead.loadBE(UInt32.self, at: 16))
        let codeSlotCount = Int(directoryHead.loadBE(UInt32.self, at: 28))
        let codeLimit = Int(directoryHead.loadBE(UInt32.self, at: 32))
        let hashSize = Int(directoryHead[directoryHead.startIndex + 36])
        let hashType = directoryHead[directoryHead.startIndex + 37]
        let pageSizeLog2 = directoryHead[directoryHead.startIndex + 39]

        // Only SHA-256 slots are recomputable here. A cache signed with
        // anything else needs its own code path, and guessing would write
        // 32 bytes of the wrong digest into a 20-byte slot.
        guard hashType == hashTypeSHA256, hashSize == 32 else { return nil }
        let pageSize = 1 << Int(pageSizeLog2)
        guard pageSize > 0, pageSize <= (1 << 20) else { return nil }

        return DyldSharedCacheChunkCodeDirectory(
            blobOffset: Int(blobOffset),
            blobLength: blobLength,
            hashOffset: hashOffset,
            hashSize: hashSize,
            codeSlotCount: codeSlotCount,
            codeLimit: codeLimit,
            pageSize: pageSize,
        )
    }

    // MARK: - Re-signing

    /// Where diagnostics go when the caller does not say.
    ///
    /// `cfw_dsc_codesign.reattest_modified_pages` defaults to `verbose=True`
    /// and prints every skip it makes. Defaulting this to `nil` was how the
    /// port lost that: an unmapped address, an unsigned chunk and an empty
    /// input all came back as an empty array with nothing written anywhere.
    /// Callers that really want silence pass `log: nil` and read the returned
    /// `DyldSharedCacheReattestation` instead.
    public static let stderrLog: @Sendable (String) -> Void = { line in
        FileHandle.standardError.write(Data((line + "\n").utf8))
    }

    /// Recompute and store the slot hash of every 16 KiB page any of
    /// `modifiedSpans` touched.
    ///
    /// Spans, not addresses, on purpose. A span knows its length, so an 8-byte
    /// write four bytes before a page boundary dirties two pages and both get
    /// re-hashed. The address-only version of this could not know that and
    /// silently left the second page stale — a `KERN_PROTECTION_FAILURE` the
    /// first time the guest demand-paged it in.
    ///
    /// Pages are coalesced, so patching four sites in one page costs one hash.
    /// A page whose stored slot already matches what the page hashes to is left
    /// alone and reported in `alreadyAttested`, which is what makes a second
    /// run over an already-patched cache a no-op rather than a rewrite.
    @discardableResult
    public static func reattest(
        in chunks: DyldSharedCacheChunkSet,
        modifiedSpans: some Sequence<DyldSharedCacheWriteSpan>,
        dryRun: Bool = false,
        log: ((String) -> Void)? = stderrLog,
    ) throws -> DyldSharedCacheReattestation {
        var pagesByChunk: [URL: Set<Int>] = [:]
        var directories: [URL: DyldSharedCacheChunkCodeDirectory?] = [:]
        var skipped: [DyldSharedCacheReattestationSkip] = []

        func skip(_ reason: DyldSharedCacheReattestationSkip.Reason) {
            skipped.append(DyldSharedCacheReattestationSkip(reason: reason))
            log?("      [-] re-attest: \(reason) — skipping")
        }

        for span in modifiedSpans {
            let chunkURL: URL
            let byteRange: Range<Int>
            do {
                (chunkURL, byteRange) = try chunks.fileRange(of: span)
            } catch DyldSharedCacheError.addressNotMapped {
                skip(.addressNotMapped(vma: span.vma))
                continue
            } catch DyldSharedCacheError.addressSpanCrossesChunk {
                skip(.spanNotAddressable(vma: span.vma, length: span.length))
                continue
            }

            let directory: DyldSharedCacheChunkCodeDirectory?
            if let cached = directories[chunkURL] {
                directory = cached
            } else {
                directory = try readCodeDirectory(ofChunk: chunkURL)
                directories[chunkURL] = directory
                if directory == nil {
                    skip(.chunkHasNoCodeDirectory(chunk: chunkURL.lastPathComponent))
                }
            }
            guard let directory else { continue }

            // Every page the span's bytes land in, not just the first.
            let firstPage = byteRange.lowerBound / directory.pageSize
            let lastPage = (byteRange.upperBound - 1) / directory.pageSize
            for pageIndex in firstPage ... lastPage {
                guard pageIndex < directory.codeSlotCount else {
                    skip(.pageBeyondCodeSlots(
                        chunk: chunkURL.lastPathComponent,
                        page: pageIndex,
                        codeSlotCount: directory.codeSlotCount,
                    ))
                    continue
                }
                guard (pageIndex + 1) * directory.pageSize <= directory.codeLimit else {
                    skip(.pageBeyondCodeLimit(
                        chunk: chunkURL.lastPathComponent,
                        page: pageIndex,
                        codeLimit: directory.codeLimit,
                    ))
                    continue
                }
                pagesByChunk[chunkURL, default: []].insert(pageIndex)
            }
        }

        guard !pagesByChunk.isEmpty else {
            log?(
                "      [.] re-attest: no eligible pages "
                    + "(\(skipped.count) skipped)",
            )
            return DyldSharedCacheReattestation(updated: [], alreadyAttested: [], skipped: skipped)
        }

        var records: [DyldSharedCacheSlotReattestation] = []
        var alreadyAttested: [DyldSharedCachePageReference] = []
        for chunkURL in pagesByChunk.keys.sorted(by: { $0.path < $1.path }) {
            guard let directory = directories[chunkURL] ?? nil else { continue }
            let handle = dryRun
                ? try FileHandle(forReadingFrom: chunkURL)
                : try FileHandle(forUpdating: chunkURL)
            defer { try? handle.close() }

            for pageIndex in pagesByChunk[chunkURL, default: []].sorted() {
                let pageOffset = pageIndex * directory.pageSize
                let slotOffset = directory.slotOffset(forPage: pageIndex)

                try handle.seek(toOffset: UInt64(pageOffset))
                // FileHandle hands back autoreleased buffers, and a command-line
                // run has no pool to drain them: 200,000 pages kept 3.4 GB alive.
                let pageData = try autoreleasepool { try handle.read(upToCount: directory.pageSize) } ?? Data()
                guard pageData.count == directory.pageSize else {
                    skip(.shortPageRead(
                        chunk: chunkURL.lastPathComponent,
                        page: pageIndex,
                        got: pageData.count,
                        wanted: directory.pageSize,
                    ))
                    continue
                }
                let newHash = Data(SHA256.hash(data: pageData))

                try handle.seek(toOffset: UInt64(slotOffset))
                let oldHash = try autoreleasepool { try handle.read(upToCount: directory.hashSize) } ?? Data()

                guard oldHash != newHash else {
                    alreadyAttested.append(
                        DyldSharedCachePageReference(chunkURL: chunkURL, pageIndex: pageIndex),
                    )
                    log?(
                        "      [.] re-attest: page \(pageIndex) of "
                            + "\(chunkURL.lastPathComponent) slot already matches (no-op)",
                    )
                    continue
                }

                if !dryRun {
                    try handle.seek(toOffset: UInt64(slotOffset))
                    try handle.write(contentsOf: newHash)
                }
                log?(
                    "      [+] re-attest: \(dryRun ? "would write" : "wrote") slot "
                        + "\(pageIndex) of \(chunkURL.lastPathComponent)  "
                        + "(\(Data(oldHash.prefix(4)).hex).. -> \(Data(newHash.prefix(4)).hex)..)",
                )
                records.append(
                    DyldSharedCacheSlotReattestation(
                        chunkURL: chunkURL,
                        pageIndex: pageIndex,
                        chunkOffset: pageOffset,
                        slotOffset: slotOffset,
                        hashBefore: oldHash,
                        hashAfter: newHash,
                    ),
                )
            }
        }

        log?(
            "  [+] re-attest: \(dryRun ? "would update" : "updated") \(records.count) "
                + "slot hash(es) across \(pagesByChunk.count) chunk(s), "
                + "\(alreadyAttested.count) already correct, \(skipped.count) skipped",
        )
        return DyldSharedCacheReattestation(
            updated: records,
            alreadyAttested: alreadyAttested,
            skipped: skipped,
        )
    }

    /// Re-attest every page that `chunks`'s own writes dirtied.
    ///
    /// The path a patcher should take: write through `DyldSharedCacheChunkSet.write(at:_:)`
    /// as many times as it likes, then call this. Nothing has to be told which
    /// addresses were touched, so nothing can get it wrong.
    @discardableResult
    public static func reattestRecordedWrites(
        in chunks: DyldSharedCacheChunkSet,
        dryRun: Bool = false,
        log: ((String) -> Void)? = stderrLog,
    ) throws -> DyldSharedCacheReattestation {
        try reattest(
            in: chunks,
            modifiedSpans: chunks.recordedWrites,
            dryRun: dryRun,
            log: log,
        )
    }

    // MARK: - Inspection

    /// The SHA-256 a page currently hashes to, and the slot hash stored for it.
    ///
    /// Used by tests and by idempotence checks: when the two are equal the page
    /// is already attested, whether this code wrote the slot or the Python did.
    public static func pageHashes(
        chunkURL: URL,
        pageIndex: Int,
        directory: DyldSharedCacheChunkCodeDirectory,
    ) throws -> (computed: Data, stored: Data) {
        let page = try DyldSharedCacheChunkSet.read(
            url: chunkURL,
            offset: UInt64(pageIndex * directory.pageSize),
            length: directory.pageSize,
        )
        let stored = try DyldSharedCacheChunkSet.read(
            url: chunkURL,
            offset: UInt64(directory.slotOffset(forPage: pageIndex)),
            length: directory.hashSize,
        )
        return (Data(SHA256.hash(data: page)), stored)
    }
}

// MARK: - Big-endian load

// File-private: `CustomFirmwareMachOCodeSignature` declares the same helper for the
// independent Mach-O path. The two signature paths are deliberately separate
// implementations, and keeping their helpers file-scoped is what stops them
// drifting into a shared one.
private extension Data {
    /// Load a big-endian integer without assuming the buffer is aligned.
    ///
    /// Code-signing blobs are big-endian throughout, which is the one place in
    /// a Mach-O or a dyld cache where that is true.
    func loadBE<T: FixedWidthInteger>(_: T.Type, at offset: Int) -> T {
        precondition(offset >= 0 && offset + MemoryLayout<T>.size <= count)
        var value: T = .zero
        _ = Swift.withUnsafeMutableBytes(of: &value) { destination in
            copyBytes(to: destination, from: offset ..< offset + MemoryLayout<T>.size)
        }
        return T(bigEndian: value)
    }
}