Run a virtual iPhone on an Apple Silicon Mac.
Swift
import Darwin
import Foundation
/// A validated `vphone-cli cfw install`, `cfw update-environment`, `cfw
/// update-kernel` or `fw patch` invocation. Built only from a store bundle whose cdhash still matches its
/// receipt, and only for a VM directory the calling user owns.
struct VPhoneLaunchpadHelperFirmwareRequest {
enum Operation {
/// The full install, which needs the prepared restore tree.
case install(keepArtifacts: Bool)
/// Redeploys the bundle's guest resources into a stopped machine and
/// nothing else.
case updateEnvironment
/// Swaps the Preboot kernelcache for the re-patched one, keeping data.
case updateKernel
/// `fw patch` with the machine's recorded selection, for a preset that
/// merges and reseals the system image before the restore. `fw patch`
/// refuses to run as root for any other selection.
case patchRestoreImage
/// `fw kernelcache --link-only`: links the kernelcache mix the user
/// staged. It never stages, so no ipsw runs as root.
case linkKernelcache
}
typealias MachineKey = VPhoneLaunchpadHelperFirmwareAdmission.MachineKey
/// CFW keeps its scratch files beside the VM when that VM is on a mounted
/// external volume. The child directory is root-owned and private. Internal
/// libraries retain the system temporary directory.
static let defaultWorkParent = "/private/var/tmp"
let executable: URL
let arguments: [String]
let environment: [String: String]
let workingDirectory: URL
let machineKey: MachineKey
/// The volumes the run writes to, by device, each with a path on it: the
/// machine folder's and the work parent's. One entry when they share one.
let volumes: [dev_t: String]
init(
operation: Operation,
bundleVersion: String,
machineName: String,
libraryRoot: String,
callerUID: uid_t,
callerGID: gid_t,
) throws {
guard VPhoneLaunchpadNames.isCompatibleBundleVersion(bundleVersion) else {
throw VPhoneLaunchpadHelperError("VPhone.bundle \(bundleVersion) is not supported. Use \(VPhoneLaunchpadNames.minimumBundleVersion) or newer.")
}
guard let receipt = VPhoneLaunchpadBundleReceipt.load(version: bundleVersion) else {
throw VPhoneLaunchpadHelperError("VPhone.bundle \(bundleVersion) is not installed. Install it in Core Bundle, then try again.")
}
let executable = VPhoneLaunchpadBundleStore.executable(version: bundleVersion, named: "vphone-cli")
try VPhoneLaunchpadHelperCodeCheck.requireCDHash(executable, receipt.cdhashes["vphone-cli"])
guard VPhoneLaunchpadNames.isValidMachineName(machineName) else {
throw VPhoneLaunchpadHelperError("\"\(machineName)\" is not a valid machine name.")
}
// Checked by walking the path from "/" without following any link:
// the library folder, the machine folder and its Disk.img must belong
// to the caller. The caller can still rename these afterwards, so this
// only refuses a bad request up front; the root vphone-cli child pins
// the machine directory again itself before it touches anything.
let folder = try Self.requireMachine(libraryRoot: libraryRoot, machineName: machineName, ownedBy: callerUID)
let machine = URL(fileURLWithPath: libraryRoot, isDirectory: true)
.appendingPathComponent(machineName, isDirectory: true)
let workParent = try Self.resolveWorkParent(
libraryRoot: libraryRoot,
callerUID: callerUID,
callerGID: callerGID,
)
var work = stat()
guard stat(workParent, &work) == 0 else {
throw VPhoneLaunchpadHelperError("Unable to read \(workParent): \(String(cString: strerror(errno)))")
}
var arguments: [String]
switch operation {
case let .install(keepArtifacts):
arguments = ["cfw", "install", machineName, "--library-root", libraryRoot,
"--work-parent", workParent]
if keepArtifacts {
arguments.append("--keep-artifacts")
}
case .updateEnvironment:
arguments = ["cfw", "update-environment", machineName, "--library-root", libraryRoot,
"--work-parent", workParent]
case .updateKernel:
arguments = ["cfw", "update-kernel", machineName, "--library-root", libraryRoot,
"--work-parent", workParent]
case .patchRestoreImage:
arguments = ["fw", "patch", machineName, "--library-root", libraryRoot, "--restore-image-only", "--work-parent", workParent]
case .linkKernelcache:
arguments = ["fw", "kernelcache", machineName, "--library-root", libraryRoot,
"--link-only", "--work-parent", workParent]
}
self.executable = executable
self.arguments = arguments
workingDirectory = machine
machineKey = MachineKey(device: folder.st_dev, inode: folder.st_ino)
// Not one literal: equal keys in a dictionary literal trap.
var volumes = [work.st_dev: workParent]
volumes[folder.st_dev] = machine.path
self.volumes = volumes
// The same environment `sudo vphone-cli cfw install` sees: SUDO_UID
// and SUDO_GID are how the installer hands root-created files back
// to the user afterwards.
environment = try VPhoneLaunchpadHelperLibraryPath.environment(callerUID: callerUID, callerGID: callerGID)
}
/// Selects a protected scratch directory on the VM's mounted external
/// volume. A user-writable volume root is refused: root must not create a
/// directory where the caller can race or replace it.
private static func resolveWorkParent(
libraryRoot: String,
callerUID: uid_t,
callerGID: gid_t,
) throws -> String {
let library = try VPhoneLaunchpadHelperLibraryPath.openDirectory(libraryRoot)
defer { close(library) }
var filesystem = statfs()
guard fstatfs(library, &filesystem) == 0 else {
throw VPhoneLaunchpadHelperError("Unable to determine the VM library's volume.")
}
let mountPoint = withUnsafePointer(to: &filesystem.f_mntonname) {
$0.withMemoryRebound(to: CChar.self, capacity: Int(MAXPATHLEN)) { String(cString: $0) }
}
guard mountPoint.hasPrefix("/Volumes/"), mountPoint != "/Volumes" else {
return defaultWorkParent
}
let volume = try VPhoneLaunchpadHelperLibraryPath.openDirectory(mountPoint)
defer { close(volume) }
var volumeInfo = stat()
guard fstat(volume, &volumeInfo) == 0, volumeInfo.st_uid == 0 else {
throw VPhoneLaunchpadHelperError("The external volume root must be owned by root before CFW can use it for temporary files.")
}
guard try !callerCanWrite(volumeInfo, callerUID: callerUID, callerGID: callerGID) else {
throw VPhoneLaunchpadHelperError("The external volume root is writable by your account; refusing to place privileged CFW temporary files there.")
}
let leaf = ".vphone-cfw-work"
if mkdirat(volume, leaf, 0o700) != 0, errno != EEXIST {
throw VPhoneLaunchpadHelperError("Unable to create the CFW work directory on \(mountPoint): \(String(cString: strerror(errno)))")
}
let work = openat(volume, leaf, O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC)
guard work >= 0 else {
throw VPhoneLaunchpadHelperError("The CFW work directory on \(mountPoint) is not a real directory.")
}
defer { close(work) }
var workInfo = stat()
guard fstat(work, &workInfo) == 0,
workInfo.st_uid == 0,
(workInfo.st_mode & S_IFMT) == S_IFDIR,
(workInfo.st_mode & 0o077) == 0
else {
throw VPhoneLaunchpadHelperError("\(mountPoint)/\(leaf) must be a root-owned private directory.")
}
return mountPoint + "/" + leaf
}
private static func callerCanWrite(
_ directory: stat,
callerUID: uid_t,
callerGID: gid_t,
) throws -> Bool {
let mode = directory.st_mode & 0o777
if callerUID == directory.st_uid {
return mode & 0o200 != 0
}
guard let account = getpwuid(callerUID) else {
throw VPhoneLaunchpadHelperError("Unable to find the user account for the CFW request.")
}
var groups = [Int32](repeating: 0, count: 256)
var count = Int32(groups.count)
let found = String(cString: account.pointee.pw_name).withCString {
getgrouplist($0, Int32(callerGID), &groups, &count)
}
guard found >= 0 else {
throw VPhoneLaunchpadHelperError("Unable to check permissions on the external volume root.")
}
if groups.prefix(Int(count)).contains(Int32(directory.st_gid)) {
return mode & 0o020 != 0
}
return mode & 0o002 != 0
}
/// The machine a cancel names. It checks no ownership: the operation
/// found under the key is stopped only for the user who started it.
static func machineKey(libraryRoot: String, machineName: String) throws -> MachineKey {
guard VPhoneLaunchpadNames.isValidMachineName(machineName) else {
throw VPhoneLaunchpadHelperError("\"\(machineName)\" is not a valid machine name.")
}
let root = try VPhoneLaunchpadHelperLibraryPath.openDirectory(libraryRoot)
defer { close(root) }
let machine = try openMachine(root, libraryRoot: libraryRoot, machineName: machineName)
defer { close(machine) }
var folder = stat()
guard fstat(machine, &folder) == 0 else {
throw VPhoneLaunchpadHelperError("\(libraryRoot)/\(machineName) is not a folder.")
}
return MachineKey(device: folder.st_dev, inode: folder.st_ino)
}
// MARK: - Machine directory
/// Returns the machine folder's metadata.
private static func requireMachine(libraryRoot: String, machineName: String, ownedBy uid: uid_t) throws -> stat {
let root = try VPhoneLaunchpadHelperLibraryPath.openDirectory(libraryRoot)
defer { close(root) }
try VPhoneLaunchpadHelperLibraryPath.requireOwner(root, libraryRoot, uid)
let machinePath = libraryRoot + "/" + machineName
let machine = try openMachine(root, libraryRoot: libraryRoot, machineName: machineName)
defer { close(machine) }
try VPhoneLaunchpadHelperLibraryPath.requireOwner(machine, machinePath, uid)
var disk = stat()
guard fstatat(machine, "Disk.img", &disk, AT_SYMLINK_NOFOLLOW) == 0,
(disk.st_mode & S_IFMT) == S_IFREG,
disk.st_nlink == 1
else {
throw VPhoneLaunchpadHelperError("\(machinePath)/Disk.img must be a regular file, not a link.")
}
guard disk.st_uid == uid else {
throw VPhoneLaunchpadHelperError("\(machinePath)/Disk.img is not owned by your user account.")
}
var folder = stat()
guard fstat(machine, &folder) == 0 else {
throw VPhoneLaunchpadHelperError("\(machinePath) is not a folder.")
}
return folder
}
private static func openMachine(_ root: Int32, libraryRoot: String, machineName: String) throws -> Int32 {
let machine = openat(root, machineName, O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC)
guard machine >= 0 else {
throw VPhoneLaunchpadHelperError("\(libraryRoot)/\(machineName) is not a folder, or is a symbolic link.")
}
return machine
}
}