Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Allow offline PCC GPU bundle during firmware preparation

Lakr8758b41d86e8
diff --git a/docs/guides/create-and-run.md b/docs/guides/create-and-run.md
index 4a53a80d..b702fe18 100644
--- a/docs/guides/create-and-run.md
+++ b/docs/guides/create-and-run.md
@@ -17,6 +17,8 @@ vphone-cli vm create myphone \
Creation runs prepare → JB patch → online DFU restore → host-mounted CFW installation → first GUI boot. It needs network access for the restore ticket. CFW installation needs administrator authentication; on a host without an interactive terminal, `--root-popup` uses a macOS authentication dialog. The default virtual disk is 64 GB. `--keep-artifacts` retains the large prepared restore tree; omit it when disk space matters.
+If Apple's WKMS server no longer serves the AEA key for the selected PCC image, `vm create` and `fw prepare` accept `--gpu-driver-bundle /path/to/AppleParavirtGPUMetalIOGPUFamily.bundle`. Supply a complete bundle previously extracted from **the same cloudOS build**. The CLI validates its files and identifier, then stages it in the restore tree without decrypting the PCC OS image. The iPhone restore still uses its own AEA keys and an online restore ticket.
+
Success ends with `First boot: vphoned ping succeeded` and `JB VM created; vphoned connected`. **The verification VM is then stopped.** The ping proves the daemon answered over the host control socket during that boot; it does not leave a running VM behind.
```sh
diff --git a/research/0_binary_patch_comparison.md b/research/0_binary_patch_comparison.md
index 5fdc5a0f..53d02b30 100644
--- a/research/0_binary_patch_comparison.md
+++ b/research/0_binary_patch_comparison.md
@@ -437,7 +437,7 @@ and nothing resolves a `python3` at runtime.
| # | Component | Description | Regular | Dev | JB |
| --- | -------------------------- | ------------------------------------------------------------------------------------------------------------------ | :-----: | :-: | :-: |
| 1 | Cryptex SystemOS + AppOS | Decrypt AEA + mount + copy to device | Y | Y | Y |
-| 2 | GPU driver | AppleParavirtGPUMetalIOGPUFamily bundle, extracted from the selected PCC OS image during `fw prepare` | Y | Y | Y |
+| 2 | GPU driver | AppleParavirtGPUMetalIOGPUFamily bundle, extracted from the selected PCC OS image during `fw prepare`, or supplied from the same cloudOS build with `--gpu-driver-bundle` if Apple's AEA key is unavailable | Y | Y | Y |
| 3 | `iosbinpack64` | Jailbreak tools (base set) | Y | Y | Y |
| 4 | `iosbinpack64` dev overlay | Replace `rpcserver_ios` with dev build | - | Y | - |
| 5 | `vphoned` | vsock HID/control daemon (built + signed) | Y | Y | Y |
diff --git a/sources/VPhoneCore/VPhonePCCGPUDriver.swift b/sources/VPhoneCore/VPhonePCCGPUDriver.swift
index 18114852..ea130eaa 100644
--- a/sources/VPhoneCore/VPhonePCCGPUDriver.swift
+++ b/sources/VPhoneCore/VPhonePCCGPUDriver.swift
@@ -9,6 +9,7 @@ public enum VPhonePCCGPUDriver {
case missingOSPath(URL)
case unsafeOSPath(String)
case missingBundle(URL)
+ case invalidCachedBundle(URL)
case toolFailed(String, String)
public var errorDescription: String? {
@@ -19,6 +20,8 @@ public enum VPhonePCCGPUDriver {
"PCC manifest has an unsafe OS image path: \(path)"
case let .missingBundle(path):
"PCC OS image has no GPU driver bundle at \(path.path)"
+ case let .invalidCachedBundle(path):
+ "GPU driver bundle is incomplete or has the wrong identifier: \(path.path)"
case let .toolFailed(tool, detail):
"\(tool) failed while extracting the PCC GPU driver: \(detail)"
}
@@ -53,10 +56,27 @@ public enum VPhonePCCGPUDriver {
/// Called during `fw prepare`, while the extracted PCC tree still exists.
/// Only the small bundle survives in the VM's restore tree; the decrypted
/// system image and mount are discarded before firmware preparation ends.
- public static func stage(from cloudOSDirectory: URL, into restoreDirectory: URL) throws {
+ public static func stage(
+ from cloudOSDirectory: URL,
+ into restoreDirectory: URL,
+ cachedBundle: URL? = nil,
+ ) throws {
let fm = FileManager.default
- let encrypted = try osImage(in: cloudOSDirectory)
let destination = stagedBundle(in: restoreDirectory)
+ if let cachedBundle {
+ let source = cachedBundle.standardizedFileURL.resolvingSymlinksInPath()
+ try validateBundle(at: source)
+ try fm.createDirectory(at: destination.deletingLastPathComponent(),
+ withIntermediateDirectories: true)
+ if fm.fileExists(atPath: destination.path) {
+ try fm.removeItem(at: destination)
+ }
+ try fm.copyItem(at: source, to: destination)
+ print("[+] GPU driver staged from local bundle: \(destination.path)")
+ return
+ }
+
+ let encrypted = try osImage(in: cloudOSDirectory)
let scratch = restoreDirectory.appendingPathComponent(".pcc-gpu-extract-\(UUID().uuidString)")
let plain = scratch.appendingPathComponent("OS.dmg")
let mount = scratch.appendingPathComponent("mount")
@@ -94,6 +114,29 @@ public enum VPhonePCCGPUDriver {
print("[+] GPU driver staged from PCC OS: \(destination.path)")
}
+ private static func validateBundle(at source: URL) throws {
+ let fm = FileManager.default
+ var isDirectory: ObjCBool = false
+ guard fm.fileExists(atPath: source.path, isDirectory: &isDirectory), isDirectory.boolValue else {
+ throw Error.invalidCachedBundle(source)
+ }
+ for file in ["AppleParavirtGPUMetalIOGPUFamily",
+ "libAppleParavirtCompilerPluginIOGPUFamily.dylib", "Info.plist",
+ "_CodeSignature/CodeResources"]
+ {
+ guard fm.fileExists(atPath: source.appendingPathComponent(file).path) else {
+ throw Error.invalidCachedBundle(source)
+ }
+ }
+ let infoURL = source.appendingPathComponent("Info.plist")
+ let info = try Data(contentsOf: infoURL, options: .mappedIfSafe)
+ let plist = try PropertyListSerialization.propertyList(from: info, format: nil)
+ guard let properties = plist as? [String: Any],
+ properties["CFBundleIdentifier"] as? String ==
+ "com.apple.driver.AppleParavirtGPUMetalIOGPUFamily"
+ else { throw Error.invalidCachedBundle(source) }
+ }
+
private static func run(_ tool: String, _ args: [String]) throws {
let result = try VPhoneProcessRunner.runCapturing(URL(fileURLWithPath: tool), args)
guard result.succeeded else {
diff --git a/sources/vphone-cli/VPhoneCreateOptions.swift b/sources/vphone-cli/VPhoneCreateOptions.swift
index ade93d5c..1c1a96c4 100644
--- a/sources/vphone-cli/VPhoneCreateOptions.swift
+++ b/sources/vphone-cli/VPhoneCreateOptions.swift
@@ -1,3 +1,4 @@
+import Foundation
import VPhoneCore
// MARK: - Create Options
@@ -7,6 +8,7 @@ public extension VPhoneCreateOrchestrator {
public var name: String
public var iphoneSource: String?
public var cloudosSource: String?
+ public var gpuDriverBundle: URL?
public var sudoPassword: String?
public var forceDSCMaxSlide: Bool
public var enableFrida: Bool
@@ -21,6 +23,7 @@ public extension VPhoneCreateOrchestrator {
name: String,
iphoneSource: String? = nil,
cloudosSource: String? = nil,
+ gpuDriverBundle: URL? = nil,
sudoPassword: String? = nil,
forceDSCMaxSlide: Bool = false,
enableFrida: Bool = false,
@@ -34,6 +37,7 @@ public extension VPhoneCreateOrchestrator {
self.name = name
self.iphoneSource = iphoneSource
self.cloudosSource = cloudosSource
+ self.gpuDriverBundle = gpuDriverBundle
self.sudoPassword = sudoPassword
self.forceDSCMaxSlide = forceDSCMaxSlide
self.enableFrida = enableFrida
diff --git a/sources/vphone-cli/VPhoneCreateOrchestrator.swift b/sources/vphone-cli/VPhoneCreateOrchestrator.swift
index 9069e7c0..546979c9 100644
--- a/sources/vphone-cli/VPhoneCreateOrchestrator.swift
+++ b/sources/vphone-cli/VPhoneCreateOrchestrator.swift
@@ -246,6 +246,7 @@ public struct VPhoneCreateOrchestrator {
let bundle = try VPhoneBundle.load(at: bundleURL)
try VPhoneFirmwarePreparer.prepare(
iPhoneSource: phone, cloudOSSource: cloud,
+ gpuDriverBundle: options.gpuDriverBundle,
bundle: bundle, cacheDirectory: resources.ipswCacheDir,
)
print("[+] Firmware prepared (iPhone + cloudOS merged into bundle).")
diff --git a/sources/vphone-cli/VPhoneFWCLI.swift b/sources/vphone-cli/VPhoneFWCLI.swift
index 9b978673..99757df4 100644
--- a/sources/vphone-cli/VPhoneFWCLI.swift
+++ b/sources/vphone-cli/VPhoneFWCLI.swift
@@ -200,6 +200,8 @@ struct VPhoneFWPrepareCommand: ParsableCommand {
@Argument(help: "VM name") var name: String?
@Option(name: .shortAndLong, help: "iPhone IPSW URL or local path") var iphoneSource: String?
@Option(name: .shortAndLong, help: "cloudOS IPSW URL or local path") var cloudosSource: String?
+ @Option(help: "GPU driver bundle from the same cloudOS build, for offline AEA recovery")
+ var gpuDriverBundle: String?
@Option(help: "iPhone version to resolve to an IPSW") var iphoneVersion: String?
@Option(help: "iPhone build to resolve to an IPSW") var iphoneBuild: String?
@Flag(help: "List downloadable IPSWs and exit") var list = false
@@ -256,6 +258,7 @@ struct VPhoneFWPrepareCommand: ParsableCommand {
let bundle = try lib.library.bundle(named: name)
try VPhoneFirmwarePreparer.prepare(
iPhoneSource: phone, cloudOSSource: cloud,
+ gpuDriverBundle: gpuDriverBundle.map { URL(fileURLWithPath: ($0 as NSString).expandingTildeInPath) },
bundle: bundle, cacheDirectory: resources.ipswCacheDir,
)
}
diff --git a/sources/vphone-cli/VPhoneFirmwarePreparer.swift b/sources/vphone-cli/VPhoneFirmwarePreparer.swift
index 600a1ea1..a6477c79 100644
--- a/sources/vphone-cli/VPhoneFirmwarePreparer.swift
+++ b/sources/vphone-cli/VPhoneFirmwarePreparer.swift
@@ -29,6 +29,7 @@ enum VPhoneFirmwarePreparer {
static func prepare(
iPhoneSource: String,
cloudOSSource: String,
+ gpuDriverBundle: URL? = nil,
bundle: VPhoneBundle,
cacheDirectory: URL,
) throws {
@@ -72,8 +73,12 @@ enum VPhoneFirmwarePreparer {
let originalManifest = phoneTree.appendingPathComponent("BuildManifest.plist")
try clone(originalManifest, to: phoneTree.appendingPathComponent("iPhone-BuildManifest.plist"))
try FirmwareManifest.generate(iPhoneDir: phoneTree, cloudOSDir: cloudTree, verbose: true)
- print("[*] Extracting GPU driver from cloudOS PCC image...")
- try VPhonePCCGPUDriver.stage(from: cloudTree, into: phoneTree)
+ print(gpuDriverBundle == nil
+ ? "[*] Extracting GPU driver from cloudOS PCC image..."
+ : "[*] Staging GPU driver from local bundle...")
+ try VPhonePCCGPUDriver.stage(
+ from: cloudTree, into: phoneTree, cachedBundle: gpuDriverBundle,
+ )
// The destination did not exist at entry and the staging directory is
// on the same volume. One rename exposes the complete restore tree.
diff --git a/sources/vphone-cli/VPhoneVMCreateCLI.swift b/sources/vphone-cli/VPhoneVMCreateCLI.swift
index d15c813c..b532068e 100644
--- a/sources/vphone-cli/VPhoneVMCreateCLI.swift
+++ b/sources/vphone-cli/VPhoneVMCreateCLI.swift
@@ -14,6 +14,8 @@ struct VPhoneVMCreateCommand: ParsableCommand {
@Argument(help: "new VM name") var name: String
@Option(name: .shortAndLong, help: "iPhone IPSW URL or local path") var iphoneSource: String?
@Option(name: .shortAndLong, help: "cloudOS IPSW URL or local path") var cloudosSource: String?
+ @Option(help: "GPU driver bundle from the same cloudOS build, for offline AEA recovery")
+ var gpuDriverBundle: String?
@Option(name: .shortAndLong, help: "Disk size (GB)") var diskSize: UInt64 = 64
@Option(name: .shortAndLong, help: "sudo password for the CFW host-mount install (via askpass; never logged)")
var sudoPassword: String?
@@ -62,6 +64,7 @@ struct VPhoneVMCreateCommand: ParsableCommand {
name: name,
iphoneSource: sources.iphoneSource,
cloudosSource: sources.cloudosSource,
+ gpuDriverBundle: gpuDriverBundle.map { URL(fileURLWithPath: ($0 as NSString).expandingTildeInPath) },
sudoPassword: sudoPassword,
forceDSCMaxSlide: forceDSCMaxSlide,
enableFrida: frida,
diff --git a/tests/VPhoneCoreTests/PCCGPUDriverTests.swift b/tests/VPhoneCoreTests/PCCGPUDriverTests.swift
index d6c1cc78..a3d33bd5 100644
--- a/tests/VPhoneCoreTests/PCCGPUDriverTests.swift
+++ b/tests/VPhoneCoreTests/PCCGPUDriverTests.swift
@@ -40,6 +40,43 @@ struct PCCGPUDriverTests {
}
}
+ @Test func `stages a validated local bundle without an AEA key request`() throws {
+ let root = FileManager.default.temporaryDirectory
+ .appendingPathComponent("pcc-gpu-test-\(UUID().uuidString)")
+ defer { try? FileManager.default.removeItem(at: root) }
+ let source = root.appendingPathComponent(VPhonePCCGPUDriver.name)
+ try FileManager.default.createDirectory(
+ at: source.appendingPathComponent("_CodeSignature"), withIntermediateDirectories: true,
+ )
+ for file in ["AppleParavirtGPUMetalIOGPUFamily",
+ "libAppleParavirtCompilerPluginIOGPUFamily.dylib",
+ "_CodeSignature/CodeResources"]
+ {
+ try Data(file.utf8).write(to: source.appendingPathComponent(file))
+ }
+ let info = try PropertyListSerialization.data(
+ fromPropertyList: ["CFBundleIdentifier":
+ "com.apple.driver.AppleParavirtGPUMetalIOGPUFamily"],
+ format: .binary, options: 0,
+ )
+ try info.write(to: source.appendingPathComponent("Info.plist"))
+
+ let restore = root.appendingPathComponent("restore")
+ try VPhonePCCGPUDriver.stage(
+ from: root.appendingPathComponent("missing-cloudos"),
+ into: restore,
+ cachedBundle: source,
+ )
+ let staged = VPhonePCCGPUDriver.stagedBundle(in: restore)
+ #expect(try Data(contentsOf: staged.appendingPathComponent("AppleParavirtGPUMetalIOGPUFamily"))
+ == Data("AppleParavirtGPUMetalIOGPUFamily".utf8))
+
+ try FileManager.default.removeItem(at: source.appendingPathComponent("_CodeSignature/CodeResources"))
+ #expect(throws: VPhonePCCGPUDriver.Error.self) {
+ try VPhonePCCGPUDriver.stage(from: root, into: restore, cachedBundle: source)
+ }
+ }
+
private func identity(device: String, os: String) -> [String: Any] {
["Info": ["DeviceClass": device],
"Manifest": ["OS": ["Info": ["Path": os]]]]