Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
8.0 KB
Raw Blame
import Foundation
import Security

// MARK: - VPhoneGuestLaunchError

public enum VPhoneGuestLaunchError: Error, CustomStringConvertible {
    case missingCompanion(name: String, expectedAt: URL)
    /// amfid refused `vphone-vm`. Carries what the advice needs to be concrete:
    /// the binary that was refused and, when it could be read, its cdhash.
    case blockedByAMFI(guest: URL, cdHash: String?)
    case missingEntitlements(guest: URL)
    case probeFailed(exitCode: Int32, output: String)

    public var description: String {
        switch self {
        case let .missingCompanion(name, url):
            return """
            \(name) not found at \(url.path). The app bundle is incomplete. Rebuild the VPhone scheme in Xcode.
            """

        case let .blockedByAMFI(guest, cdHash):
            let helper = guest.deletingLastPathComponent()
                .appendingPathComponent("vphone-escalator")
            return """
            AMFI blocked vphone-vm, so the VM could not start.

            Binary: \(guest.path)
            CDHash: \(cdHash ?? "unavailable")

            Allow this build's signed VM binary with the bundled helper:
              sudo '\(helper.path)' allow '\(guest.path)'

            The allowlist is specific to this signature, so repeat after a
            rebuild. See https://github.com/Lakr233/vphone-cli/blob/main/Documents/en/get-started/host-setup.md
            for host settings.
            """

        case let .missingEntitlements(guest):
            return """
            vphone-vm at \(guest.path) is missing required virtualization entitlements.
            Rebuild the VPhone scheme in Xcode to sign this binary, then allow the new signature
            through the host's AMFI policy before launching a VM.
            """

        case let .probeFailed(code, output):
            return """
            vphone-vm could not start (exit code \(code)). AMFI did not block it.
            \(output.isEmpty ? "It produced no output." : output)
            """
        }
    }
}

// MARK: - VPhoneGuestLaunchPlanner

/// Decides, once, whether a guest can be started at all, then hands out the
/// concrete command for each boot.
///
/// The two binaries are split precisely so this indirection can exist:
/// `vphone-vm` carries the private virtualization entitlements and therefore
/// cannot launch unless amfid is willing, while `vphone-cli` carries none and
/// always launches. That makes `vphone-cli` the one process that is still
/// running when the refusal happens, and so the only one that can explain it.
///
/// Explaining is now all it does. It used to open an AMFI window itself, by
/// running a root helper that patched amfid's `__TEXT` for the length of one
/// launch; a host with `vm.cs_system_enforcement` set kills amfid outright for
/// that dirty page, so the helper was removed. Getting past amfid is the
/// user's own business now, and `VPhoneGuestLaunchError.blockedByAMFI` is what
/// tells them how.
///
/// It is a value rather than a set of static calls because `vm create` boots
/// the guest more than once, and probing amfid once per boot would be wasteful.
public struct VPhoneGuestLaunchPlanner: Sendable {
    /// The guest binary. Host preflight checks this, because this is the
    /// binary that actually has to satisfy amfid.
    public let guestExecutable: URL

    public init() throws {
        let vm = VPhoneResources.siblingExecutable("vphone-vm")
        guard FileManager.default.isExecutableFile(atPath: vm.path) else {
            throw VPhoneGuestLaunchError.missingCompanion(name: "vphone-vm", expectedAt: vm)
        }
        guestExecutable = vm

        // `swift test -c release` can replace a signed release binary with
        // its linker-signed, unentitled build. That binary answers --help, but
        // PV=3 isSupported is false when the VM is created.
        guard try Self.hasRequiredEntitlements(vm) else {
            throw VPhoneGuestLaunchError.missingEntitlements(guest: vm)
        }

        // Probe before doing anything else. Launching straight into a SIGKILL
        // would leave the caller with a bare exit 9 and no explanation — which
        // is the confusing failure this whole path exists to remove.
        if try Self.amfidRefuses(vm) {
            throw VPhoneGuestLaunchError.blockedByAMFI(
                guest: vm,
                cdHash: Self.codeDirectoryHash(of: vm),
            )
        }
    }

    /// The command to spawn for one boot.
    public func plan(_ arguments: [String]) -> (executable: URL, arguments: [String]) {
        (guestExecutable, arguments)
    }

    /// Run a guest to completion and return its exit status.
    ///
    /// stdio is inherited so the guest's serial output streams straight to the
    /// terminal, and the child is placed in the terminal's foreground group so
    /// that Ctrl-C behaves normally.
    @discardableResult
    public func run(_ arguments: [String], cwd: URL? = nil) throws -> Int32 {
        let (exe, args) = plan(arguments)
        return try VPhoneProcessRunner.runForeground(exe, args, cwd: cwd)
    }

    // MARK: - Probe

    private static func hasRequiredEntitlements(_ vm: URL) throws -> Bool {
        let result = try VPhoneProcessRunner.runCapturing(
            URL(fileURLWithPath: "/usr/bin/codesign"),
            ["-d", "--entitlements", "-", "--xml", vm.path],
        )
        guard result.succeeded,
              let plist = try? PropertyListSerialization.propertyList(
                  from: Data(result.stdout.utf8),
                  format: nil,
              ) as? [String: Any]
        else { return false }
        return plist["com.apple.private.virtualization"] as? Bool == true &&
            plist["com.apple.private.virtualization.security-research"] as? Bool == true
    }

    /// Ask amfid the question cheaply, by running `vphone-vm --help`.
    ///
    /// amfid decides at exec, before any of the target's own code runs, so a
    /// `--help` that never prints is the same refusal the real launch would
    /// hit — and it costs nothing and touches no VM state. A refused process is
    /// killed with SIGKILL, which Foundation reports as termination status 9.
    ///
    /// Anything else non-zero is somebody else's problem, and is raised as
    /// itself rather than being mistaken for an AMFI refusal.
    private static func amfidRefuses(_ vm: URL) throws -> Bool {
        let probe = try VPhoneProcessRunner.runCapturing(vm, ["--help"])
        if probe.succeeded {
            return false
        }
        if probe.exitCode == SIGKILL {
            return true
        }
        throw VPhoneGuestLaunchError.probeFailed(
            exitCode: probe.exitCode,
            output: (probe.stderr + probe.stdout).trimmingCharacters(in: .whitespacesAndNewlines),
        )
    }

    /// A binary's code-directory hash, in the hex form amfidont's `--cdhash`
    /// wants and `codesign -dv --verbose=4` prints.
    ///
    /// Read in-process through the Security framework rather than by spawning
    /// `codesign`: `kSecCodeInfoUnique` *is* the cdhash, straight from the
    /// code-signing machinery instead of scraped out of another tool's output.
    /// That means no subprocess on a path that is already failing, and no
    /// chance of picking up some other `codesign` from `PATH`. The two agree
    /// byte for byte — checked against `codesign -dv --verbose=4`.
    ///
    /// `nil` means the binary could not be read or is unsigned; the caller
    /// then tells the user how to obtain the hash instead of inventing one.
    static func codeDirectoryHash(of binary: URL) -> String? {
        var code: SecStaticCode?
        guard SecStaticCodeCreateWithPath(binary as CFURL, [], &code) == errSecSuccess,
              let code
        else { return nil }
        var information: CFDictionary?
        guard SecCodeCopySigningInformation(code, [], &information) == errSecSuccess,
              let entries = information as? [String: Any],
              let hash = entries[kSecCodeInfoUnique as String] as? Data
        else { return nil }
        return hash.map { String(format: "%02x", $0) }.joined()
    }
}