Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
16.5 KB
Raw Blame
// CryptexFilesystemPatcherGuestPayload.swift — Guest payload injection into the merged volume.
//
// Split out of CryptexFilesystemPatcher.swift. These are the steps that write files into the
// mounted target volume: dyld symlinks, GPU driver bundle, the mobileactivationd and
// launchd_cache_loader patches, vphoned, and its LaunchDaemon.

import Foundation
import VPhoneCoreKit
import VPhonePatchKit
import VPhoneSign

extension CryptexFilesystemPatcher {
    // MARK: - Signing

    /// Preserve a binary's existing entitlements while re-signing without an
    /// embedded certificate. The guest's JB firmware does not need a CMS
    /// identity for these binaries.
    func guestSigningOptions(
        identifier: String? = nil,
        entitlements: URL? = nil,
    ) throws -> VPhoneSignOptions {
        // Apple's ad-hoc shape, as the stock binaries around them: the guest's
        // TXM is not patched here, and it takes an ad-hoc binary from the
        // static trust cache but rejects ldid's signature, which has no
        // ad-hoc flag and an empty CMS blob ("Bad executable").
        try VPhoneSignOptions(
            identifier: identifier,
            entitlements: entitlements.map { try Data(contentsOf: $0, options: .mappedIfSafe) },
            mergesExisting: true,
            style: .appleAdHoc,
        )
    }

    func patchLaunchdCacheLoader(targetMount: String) throws {
        try editGuestFile("usr/libexec/launchd_cache_loader", targetMount: targetMount, mode: 0o755) { file in
            try thinToArm64e(file)
            // Patched in place with no `.bak` to restore from, so this is the call
            // site that needs the port's idempotence. No re-attestation: the sign
            // below replaces the whole signature anyway.
            try CustomFirmwareCacheLoaderPatcher.patch(fileAt: file)
            try setMode(0o755, at: file)

            try VPhoneSigner.sign(
                fileAt: file,
                options: guestSigningOptions(
                    identifier: "com.apple.launchd_cache_loader",
                ),
            )
        }
    }

    /// The launchd change `cfw install` makes for
    /// `system-launchd-boot-jetsam_panic_guard_bypass` (``CustomFirmwareJetsamPatcher``),
    /// in the pre-reseal merge. Re-signed ad hoc over its own entitlements, so
    /// the new hash lands in the regenerated trust cache.
    func patchLaunchdJetsam(targetMount: String) throws {
        try editGuestFile("sbin/launchd", targetMount: targetMount, mode: 0o755) { file in
            try thinToArm64e(file)
            try CustomFirmwareJetsamPatcher.patch(fileAt: file, log: { print("  \($0)") })
            try setMode(0o755, at: file)

            try VPhoneSigner.sign(
                fileAt: file,
                options: guestSigningOptions(identifier: "com.apple.xpc.launchd"),
            )
        }
        print("  [+] Patched launchd's jetsam panic guard")
    }

    func injectLaunchDaemons(targetMount: String) throws {
        let target = try VPhoneConfinedDirectory.pin(absolutePath: targetMount)
        let source = resources.guestResources.appendingPathComponent("vphoned.plist")
        try target.replaceFile("System/Library/LaunchDaemons/vphoned.plist", fromFileAt: source, mode: 0o644, owner: (0, 0))
        try editGuestFile(CustomFirmwareDetachedSignature.launchdCachePath, targetMount: targetMount, mode: 0o644) { file in
            try CustomFirmwareDaemons.injectDaemon(into: file, name: "vphoned", from: source)
        }
        print("  [+] Injected vphoned")
        try resignLaunchdCache(targetMount: targetMount)
    }

    /// Sign the edited `launchd.plist` as Apple signs it, so the stock
    /// `launchd_cache_loader` takes it as the secure cache. `createTrustcache`
    /// adds the new cdhashes to the static trust cache, which is what the loader
    /// asks AMFI about. See `CustomFirmwareDetachedSignature`.
    ///
    /// The new cdhashes take the launch-constraint category of Apple's
    /// signature, as a re-signed binary does (`resignedCDHashes`): Apple's
    /// static trust cache gives both cdhashes of its `launchd.plist.sig`
    /// category 2 (iOS 18.6 22G86).
    func resignLaunchdCache(targetMount: String) throws {
        let target = try VPhoneConfinedDirectory.pin(absolutePath: targetMount)
        let original = try target.exists(CustomFirmwareDetachedSignature.launchdCacheSignaturePath)
            ? CustomFirmwareDetachedSignature.codeDirectoryHashes(
                in: target.readData(CustomFirmwareDetachedSignature.launchdCacheSignaturePath),
            ).map(\.cdhash)
            : []
        let cache = try target.readData(CustomFirmwareDetachedSignature.launchdCachePath)
        let signature = CustomFirmwareDetachedSignature.sign(cache, identifierStem: "launchd")
        let file = try createTmpDir().appending(path: "launchd.plist.sig")
        try signature.write(to: file)
        // root:admin 0644, as Apple installs it.
        try target.replaceFile(CustomFirmwareDetachedSignature.launchdCacheSignaturePath,
                               fromFileAt: file, mode: 0o644, owner: (0, 80))
        for cdHash in original {
            print("  [+] Apple's launchd.plist.sig: cdhash \(cdHash.map { String(format: "%02x", $0) }.joined())")
        }
        for hash in try CustomFirmwareDetachedSignature.codeDirectoryHashes(in: signature) {
            if !original.isEmpty, !original.contains(hash.cdhash) {
                resignedCDHashes[hash.cdhash] = original
            }
            print("  [+] Signed launchd.plist: cdhash \(hash.cdhash.map { String(format: "%02x", $0) }.joined()) (hash type \(hash.hashType))")
        }
    }

    func addVphoned(targetMount: String) throws {
        // The signed payload in the bundle is read-only, so stage it in a
        // writable temp directory before copying it into the mounted guest.
        let buildDir = try createTmpDir()
        let vphonedBin = buildDir.appendingPathComponent("vphoned")

        try stageVphoned(to: vphonedBin)
        defer { try? FileManager.default.removeItem(at: vphonedBin) }

        let confined = try VPhoneConfinedDirectory.pin(absolutePath: targetMount)
        if guestFamily == .iPhone || guestFamily == .iPad {
            // Included in createTrustcache's scan of the finished filesystem.
            _ = try confined.directory("usr/lib/vphone", create: true)
            try confined.replaceFile("usr/lib/vphone/libswiftCompatibilitySpan.dylib",
                                     fromFileAt: VPhoneGuestBinaries.resolve("libswiftCompatibilitySpan.dylib"),
                                     mode: 0o755, owner: (0, 0))
        }
        try confined.replaceFile("usr/bin/vphoned", fromFileAt: vphonedBin, mode: 0o755, owner: (0, 0))
    }

    /// Copy in the prebuilt guest daemon.
    ///
    /// This used to be a `/usr/bin/xcrun -sdk iphoneos clang …` over the .m
    /// sources shipped inside the .app — which meant installing CFW onto a VM
    /// required Xcode and the iPhoneOS SDK on a machine whose only job is to run
    /// that VM. vphoned is cross-compiled at build time now
    /// by the Xcode guest target and staged into the bundle.
    func stageVphoned(to vphonedBin: URL) throws {
        let prebuilt = try VPhoneGuestBinaries.resolve(VPhoneResources.vphonedName(for: guestFamily))
        try FileManager.default.copyItem(at: prebuilt, to: vphonedBin)
    }

    func addGpuDriver(targetMount: String) throws {
        let target = URL(filePath: targetMount)
        let bundle = target.appending(path: "/System/Library/Extensions/AppleParavirtGPUMetalIOGPUFamily.bundle")
        let staged = VPhonePCCGPUDriver.stagedBundle(in: restoreDir)
        guard FileManager.default.fileExists(atPath: staged.path) else {
            throw VPhonePatchKit.PatcherError.patchVerificationFailed(
                "PCC GPU driver is missing: \(staged.path). Re-run fw prepare with the PCC IPSW.",
            )
        }
        let confined = try VPhoneConfinedDirectory.pin(absolutePath: targetMount)
        let relative = "System/Library/Extensions/AppleParavirtGPUMetalIOGPUFamily.bundle"
        try confined.removeItem(relative)
        let source = try VPhoneConfinedDirectory.pin(absolutePath: staged.path)
        try confined.copyTree(from: source, to: relative, owner: (0, 0))
        // Clean AppleDouble files if the host copy created any.
        try deleteAppleDoubleFiles(under: bundle)
        if guestFamily == .watch {
            try retargetGPUBundle(bundle, to: MachOBuildPlatform.watchOS)
        }
        try chownRecursively(uid: 0, gid: 0, at: bundle)
        for path in [
            bundle,
            bundle.appending(path: "/AppleParavirtGPUMetalIOGPUFamily"),
            bundle.appending(path: "/_CodeSignature"),
        ] {
            try setMode(0o755, at: path)
        }
        let compilerPlugin = bundle.appending(path: "libAppleParavirtCompilerPluginIOGPUFamily.dylib")
        guard FileManager.default.fileExists(atPath: compilerPlugin.path) else {
            throw VPhonePatchKit.PatcherError.patchVerificationFailed(
                "PCC GPU compiler plugin is missing: \(compilerPlugin.path). Re-run fw prepare with a complete vphone-cli.app.",
            )
        }
        try setMode(0o755, at: compilerPlugin)
        for path in [
            bundle.appending(path: "/_CodeSignature/CodeResources"),
            bundle.appending(path: "/Info.plist"),
        ] {
            try setMode(0o644, at: path)
        }
    }

    /// Whether the merged system is iOS 18, whose paravirtual IOSurface driver
    /// takes no compressed surfaces.
    var isIOS18: Bool {
        (try? getProductVersion())?.hasPrefix("18.") ?? false
    }

    /// iOS 18's AppleParavirtIOSurface maps only address format 0 and rejects
    /// the compressed surfaces CoreAnimation asks for ("invalid address format
    /// (3)"): backboardd's framebuffer allocation fails at boot, it retries
    /// forever, and the screen stays black. Turning off IOSurface and
    /// framebuffer compression and the deep (10-bit) framebuffer in the
    /// any-user global domain fixes it, checked across a reboot (a backboardd
    /// restart also comes up without these keys, so it proves nothing).
    /// backboardd consults neither com.apple.coreanimation nor the managed
    /// any-user file. The restore copies the image's /private/var into the
    /// data volume, so the preferences are written there.
    func addCoreAnimationDefaults(targetMount: String) throws {
        let target = try VPhoneConfinedDirectory.pin(absolutePath: targetMount)
        let directory = try target.directory("private/var/preferences", create: true)
        let plist = ".GlobalPreferences.plist"
        var preferences: [String: Any] = [:]
        if let data = try? directory.readData(plist),
           let existing = try? PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any]
        {
            preferences = existing
        }
        for key in ["CAEnableIOSurfaceCompression", "CAEnableFramebufferCompression", "CAEnableDeepFramebuffer"] {
            preferences[key] = false
        }
        let data = try PropertyListSerialization.data(fromPropertyList: preferences, format: .binary, options: 0)
        try directory.writeFile(plist, contents: data, mode: 0o644, owner: (0, 0))
    }

    /// The driver and its compiler plugin are built for iOS, and dyld refuses a
    /// library of another platform than the process's: on a watch they say
    /// watchOS, are signed again and the bundle sealed again.
    func retargetGPUBundle(_ bundle: URL, to platform: UInt32) throws {
        for name in ["AppleParavirtGPUMetalIOGPUFamily", "libAppleParavirtCompilerPluginIOGPUFamily.dylib"] {
            let file = bundle.appending(path: name)
            var data = try Data(contentsOf: file)
            try MachOBuildPlatform.set(platform, in: &data)
            try data.write(to: file)
            try VPhoneSigner.sign(
                fileAt: file,
                options: .init(identifier: nil, entitlements: nil, mergesExisting: true, style: .appleAdHoc),
            )
        }
        // No --identifier: codesign keeps the one the bundle already carries.
        _ = try runProcess("/usr/bin/codesign", ["-f", "-s", "-", "--timestamp=none", bundle.path])
        print("  [+] GPU driver retargeted to \(platform == MachOBuildPlatform.watchOS ? "watchOS" : "platform \(platform)")")
    }

    /// A watch's binaries are universal (arm64_32 and arm64e); the VM runs the
    /// arm64e slice, which is the one the patchers read. Keeps a thin binary.
    func thinToArm64e(_ file: URL) throws {
        let data = try Data(contentsOf: file)
        guard MachOFatSlice.isFat(data) else { return }
        try MachOFatSlice.slice(data).write(to: file)
    }

    func patchMobileActivation(targetMount: String) throws {
        try editGuestFile("usr/libexec/mobileactivationd", targetMount: targetMount, mode: 0o755) { file in
            try thinToArm64e(file)
            // `resign: false` because the sign below replaces the signature, and
            // re-attesting would refuse an unsigned input the Python accepted.
            try CustomFirmwareMobileActivation.patch(fileAt: file, resign: false)
            try setMode(0o755, at: file)

            try VPhoneSigner.sign(
                fileAt: file,
                options: guestSigningOptions(),
            )
        }
    }

    func addDyldSymlinks(targetMount: String) throws {
        let target = try VPhoneConfinedDirectory.pin(absolutePath: targetMount)
        try target.createSymlink(target: "../../../System/Cryptexes/OS/System/Library/Caches/com.apple.dyld",
                                 at: "System/Library/Caches/com.apple.dyld")
        try target.createSymlink(target: "../../../../System/Cryptexes/OS/System/DriverKit/System/Library/dyld",
                                 at: "System/DriverKit/System/Library/dyld")
    }

    /// Re-sign the guest's debugserver so it can attach in the guest: the same
    /// entitlement change `cfw install` makes (``CustomFirmwareDebugserver``), but
    /// in the pre-reseal merge, so debugserver's new hash lands in the image's
    /// regenerated trust cache and the stock kernel admits it. A logged no-op when
    /// the merged system ships no debugserver (a stock userland carries it only in
    /// the Developer disk image). Running and attaching also need kernel and TXM
    /// patches; ``FirmwarePatchSetCatalog/userspaceDebugging`` groups them.
    func patchDebugserver(targetMount: String) throws {
        let target = try VPhoneConfinedDirectory.pin(absolutePath: targetMount)
        let relative = CustomFirmwareDebugserver.guestPath
        guard try target.isRegularFile(relative) else {
            print("  [!] debugserver absent in the merged image; re-sign skipped")
            return
        }
        try editGuestFile(relative, targetMount: targetMount, mode: 0o755) { file in
            // A watch's debugserver also carries an arm64_32 slice, which the
            // signer cannot rewrite; the guest runs the arm64e one.
            try thinToArm64e(file)
            guard let source = try VPhoneSigner.entitlements(ofFileAt: file).first(where: { !$0.isEmpty }) else {
                throw VPhonePatchKit.PatcherError.patchVerificationFailed(
                    "debugserver has no readable entitlements; cannot grant task_for_pid",
                )
            }
            let entitlements = try CustomFirmwareDebugserver.attachEntitlements(from: source)
            // Replacement, not merge — see CustomFirmwareDebugserver.attachEntitlements.
            try VPhoneSigner.sign(
                fileAt: file,
                options: VPhoneSignOptions(entitlements: entitlements, style: .appleAdHoc),
            )
        }
        print("  [+] Re-signed debugserver with task_for_pid-allow")
    }

    /// Path-based patchers only see this private copy. Guest symlinks cannot
    /// redirect their reads or writes into the host filesystem.
    func editGuestFile(_ relative: String, targetMount: String, mode: mode_t, edit: (URL) throws -> Void) throws {
        let target = try VPhoneConfinedDirectory.pin(absolutePath: targetMount)
        let data = try target.readData(relative)
        let file = try createTmpDir().appending(path: "payload")
        try data.write(to: file)
        try edit(file)
        let original = TrustCache.cdHashes(ofMachO: data)
        for cdHash in try TrustCache.cdHashes(ofMachO: Data(contentsOf: file)) where !original.contains(cdHash) {
            resignedCDHashes[cdHash] = original
        }
        try target.replaceFile(relative, fromFileAt: file, mode: mode, owner: (0, 0))
    }

}