Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Document how the guest's device name is pinned

Jacky8825d63f2353
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
index 08e2bc66..e9dc8642 100644
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@ -566,6 +566,7 @@ do NOT execute these).
| 24 | No binary change: both spawn hooks insert `libbatteryhealthfix.dylib` into `Settings` (`/Applications/Preferences.app/Preferences`) beside SystemHook, where it interposes `IOPSCopyPowerSourcesInfo`, `IOPSCopyPowerSourcesByType`, `IOPSCopyPowerSourcesByTypePrecise`, `notify_register_check` / `notify_get_state` / `notify_cancel` and `MGGetBoolAnswer` — **all bases** | none (new guest dylib `VPhoneGuestComponents/BatteryHealthFix/libbatteryhealthfix.c`, installed at `/usr/lib/libbatteryhealthfix.dylib`) | **Stop Settings → Battery → Battery Health & Charging loading forever.** The VM's battery is Virtualization.framework's synthetic power source (charge and connectivity only), and the health half of a real battery's description comes from AppleSmartBattery, which no VM has. Measured on `iPhone17,3 27.0 (24A435)`: powerd's internal battery description has one `BatteryPacks` entry holding only `PackID`, `Cycle count` and `Transport Type`, no `Battery Service State`/`Flags` or `Maximum Capacity Percent` anywhere, and `com.apple.thermalmonitor.ageAwareMitigationState` stays 0. `-[BatteryHealthUIController specifiers]` asks `-[BatteryHealthUIInformation batteryDataUnavailable]`, which answers YES while `+getManagementState` is 0, while no pack parses (`-[BatteryHealthUIPackInformation initWithPowerSourceInformation:]` drops a pack without service flags and state), or while the overall genuine status is -1 — and it is -1 because `MGGetBoolAnswer("D6/BMDrlb8V3WSiqL8gL+w")` (HasBatteryModuleAuth, `+[PLGestaltUtilities hasBatteryModuleAuth]`) answers 1 on the guest, sending `+genuineBatteryStatusForPackIndex:` to an `AppleBatteryAuth`/`AppleAuthCPRelay` service that does not exist. The controller then shows its global spinner and re-asks on a timer. iPadOS 26.6.2 (23G90) has the same gate in `+[BatteryUIResourceClass batteryDataUnavailable]`, reading the flat keys of `IOPSCopyPowerSourcesByType`'s array, the same notify name and the same MobileGestalt key. The hook answers as a new battery without battery authentication: each internal-battery description is copied with `Battery Service State` 0, `Battery Service Flags` 0, `Maximum Capacity Percent` 100 and `Cycle count` 0 at the top level, and each of powerd's packs (or one new pack) completed with a `BatteryHealth` dictionary of the same three numbers plus `Date of manufacture`/`Date of first use` (the birth time of `/private/var/mobile`, i.e. the restore); keys already present are never replaced, and a description that already has them is passed through. A mitigation state of 0 on a token registered for the age-aware name reads as 2 ("supporting normal peak performance"). HasBatteryModuleAuth reads as no only while `IOServiceGetMatchingService("AppleBatteryAuth")` finds nothing. Interposing reaches the callers because `BatteryUsageUI.bundle` is a standalone Mach-O bound through dyld's interposing table (cache-to-cache calls are not; see `MISFix/MISFixSignature.c`), and inserting it — rather than SystemHook `dlopen`ing it like row 21 — is what puts the table in place before the bundle loads. `vpInsertedLibraryFor` in `Shared/InjectionEnvironment.h` picks it or libmisfix for a path; the two target sets do not overlap. Ships with `system-launchdaemons-boot-environment`; existing guests get it from the vphoned environment update on their next start with the new bundle (offline `cfw update-environment` only replaces libraries a VM already has). launchd starts Settings itself, so it is the launchd hook that inserts it: a guest updated only by that online sync needs one more reboot before launchd runs the new hook, which the update already reports as `reboot_required`; an offline environment update replaces the hook before boot. **Validated (2026-10-04, `bhtest-iphone`, `iPhone17,3 27.0 (24A435)` + cloudOS 26.4):** before, the page showed only the spinner and the two charging switches; after, Maximum Capacity 100%, Peak Performance Capability "Your battery is currently supporting normal peak performance", the two switches, no spinner; the hook's log shows all three answers taken once per process. Re-checked on the final bundle after a reboot of the same guest, with the launchd hook logging `inserted+batteryhealthfix` for each Settings launch. **iPad16,1 26.6.2 (23G90), `bhtest-ipad`, created with the new bundle:** the hook is inserted and stays inert, and Settings runs without a crash; that iPad has no Battery Health page at all, because `-[BatteryUIController setUpBatteryHealthGroup]` offers the row only on an iPhone or, through `+[PLBatteryUIBackendModel shouldShowModifiedHealthController]`, on an iPad that supports the fixed charge limit with the `PerfPowerServices/battery_health_details` feature on — the model decides, as on hardware. The 26.x gate inside the page is from static analysis; no 26.x iPhone image was at hand to run it. | Y | Y | Y |
| 25 | No binary change: `libvcamcaptured.dylib` stops every other thread in `cameracaptured` (`task_threads` + `thread_suspend`, self excluded, one patcher at a time) around each `vcc_patch_word` / `vcc_patch_two_nops` text rewrite — **all bases** | none (guest dylib `VPhoneGuestComponents/VCamCaptured/Image/VCamCodePatch.m`, installed at `/usr/lib/libvcamcaptured.dylib`) | **Stop the hook's own runtime patching from crashing `cameracaptured`, which froze the whole VM when the camera was opened.** The hook rewrites CMCapture shared-cache `__text` through `vm_protect(RW|COPY)` → write → `vm_protect(RX)`; for the whole flip the 16K page carries no execute permission, and the pages it touches (the `-12783` error-code sites, the master-clock gate, the prewarm call) are live XPC server code. Two crash reports caught a thread fetching an instruction in a page mid-flip while the patching thread was in `vcc_patch_word` on the same boot: `ipad-mini-01` `cameracaptured-2026-10-03-045638.ips` died in `__FigFlashlightGetClassID_block_invoke` on `com.apple.coremedia.flashlight(34)-messages`, and `ipad-pro-13` `cameracaptured-2026-10-04-225558.ips` died in `captureSourceServer_handleRegisterNotificationForProprietaryDefaultChangesMessage` on `com.apple.coremedia.capturesource(523)-messages` — the register-for-source-changes XPC that camera enumeration itself sends. Both are `EXC_BAD_ACCESS (SIGBUS)`, `KERN_PROTECTION_FAILURE` on an instruction fetch, in a region snapshotted `r-x/rwx`, `SM=COW` (the rwx max-protection is the flip's fingerprint). The card: with row 23 removing the boot crash, any later `cameracaptured` restart (jetsam, another crash) while a camera client reconnects sends its first XPCs straight into the +3 s reinstall window; one SIGBUS → launchd throttles → every AVCapture client, SpringBoard's main thread included, blocks forever in a synchronous XPC — the "VM 卡死" report of 2026-10-05. The stopped section is exactly two `vm_protect` calls, the word write and `sys_icache_invalidate`: no locks, no allocation, no logging, so a frozen thread holding any userspace lock cannot deadlock the patcher; every `vcc_log` moved after the resume, and a mutex serialises patchers (constructor prewarm patch vs the +3 s install block). All five runtime text-patching call sites (`vcc_scan_and_patch` ×2, the prewarm NOP, the session-hook pair, the source-installation NOPs) funnel through the two fixed functions. Validation: kill-and-relaunch stress with Camera.app auto-reconnecting (the same collision that produced both crashes) produces no new `cameracaptured` crash report, and the boot log's `patch_word OK` lines are unchanged. See `Research/Guest/virtual_camera_transport.md` ("The patch race that froze the whole VM"). | Y | Y | Y |
| 26 | No binary change: both spawn hooks insert `libdevicehubfix.dylib` into `cryptexd` and the DDI's `dtremotedisplayd` and `dtdeviceinfod`. In `cryptexd` it interposes `fcntl` and reports an `EPERM` from `F_SETPROTECTIONCLASS` as `ENOTSUP`; in `dtremotedisplayd` it interposes `MediaStreamSupportedFeatures.current` (answers `0x8c`) and `CurrentDevice.isCustomerRestricted` (answers false) from the DDI's `CoreDeviceUtilities`; in `dtdeviceinfod` it interposes `MGCopyAnswer` and fills a missing `FramebufferIdentifier` for `phone11` chrome — **all bases** | none (new guest dylib `VPhoneGuestComponents/DeviceHubFix/libdevicehubfix.c`, installed at `/usr/lib/libdevicehubfix.dylib`) | **Let Xcode 27's DeviceHub show the guest's screen.** On iOS 27 `cryptexd` stages each DDI asset with `open(O_RDWR)` + `fcntl(F_SETPROTECTIONCLASS, 4)` and accepts only `ENOTSUP` as a failure; a guest answers `EPERM` (`set protection class: [1: Operation not permitted]`, `staging failed`), so CoreDevice shows the device as "connected (no DDI)" for good. With the DDI mounted, DeviceHub asks `dtremotedisplayd` for its media stream features and gets 0 from CoreDeviceUtilities' policy: `isCustomerRestricted` (`isProductionFused && !hasInternalOSBuild && hasInternalDDI == false`) refuses every pre-27.0 device, and remote control is limited to iPhone, Apple Watch and Apple TV, which refuses every iPad. `0x8c` is what a Mac host reports for itself (mirrored primary display 0x4, system audio 0x8, display information 0x80). The 27.x iPhone guest reports `phone11` chrome with no `FramebufferIdentifier`, so DeviceHub drew the screen over the bezel corners; the hook answers only that missing key with Xcode's matching mask `4E5532ED-1470-47D1-BDF4-7AA90C26957A` from `/Library/Developer/DeviceKit/chrome_map.plist`. Interposing reaches all of them because `cryptexd`, `dtremotedisplayd`, `dtdeviceinfod` and `CoreDeviceUtilities` are standalone images; the two Swift symbols are weak flat-namespace imports, resolving to nothing outside `dtremotedisplayd`. On 27.x the view also needs row 11's conditional dispatch, or the capture display stays black. Ships with `system-launchdaemons-boot-environment`; an existing guest gets it from the environment update. Details: `Research/Guest/devicehub_screen_viewing.md`. **Validated (2026-10-06/07):** `iPad16,1 26.6.2 (23G90)`: DeviceHub receives `supportedFeatures: 140`, `MediaStreamStart` succeeds and the view shows the live home screen. `iPhone17,3 27.0.1 (24A446)`: the DDI mounts (`F_SETPROTECTIONCLASS EPERM, reported as ENOTSUP`), and with row 11's conditional dispatch DeviceHub shows the home screen and Settings live, clipped inside the chrome (`Found FramebufferMaskIdentifier from displayInfo`). Open: latency that grows over a long session and occasional stalls after a cold start, both upstream of the Mac receiver. | Y | Y | Y |
+| 27 | No binary change: both spawn hooks insert `libdevicename.dylib` into `configd` and `lockdownd` (after `libmisfix.dylib`, the first process to take two inserted libraries). In `configd` it interposes `SCDynamicStoreSetMultiple` and `SCDynamicStoreSetValue` and pins `Setup:/System`'s `ComputerName`; in `lockdownd` it interposes `SCPreferencesSetComputerName`, `SCPreferencesSetHostName` and `SCPreferencesSetLocalHostName` and refuses renames with `kSCStatusAccessError`. Inert unless NVRAM `vphone-device-name` holds a valid name — **all bases** | none (new guest dylib `VPhoneGuestComponents/DeviceName/libdevicename.c`, installed at `/usr/lib/libdevicename.dylib`) | **Pin the guest's device name to the one the host chose.** The name is `System/System/ComputerName` in `preferences.plist`; configd's PreferencesMonitor (`updateConfiguration`, 24A435 `0x100062098`) flattens it into `Setup:/System` with one `SCDynamicStoreSetMultiple`, and every reader (`SCDynamicStoreCopyComputerName` in lockdownd's `copy_device_name`, MobileGestalt `UserAssignedDeviceName`, `UIDevice.name`) reads the store. The hook rewrites that publication, not the preferences read: the monitor's model-change path (`sub_10006155c`) writes the `kSCPrefSystem` value it reads back to disk, and the publication route leaves `preferences.plist` with the guest's own name, so turning the feature off restores it. A publication that leaves `Setup:/System` out as unchanged gets the store's value pinned; one that removes it gets the pinned name instead, so a guest with no name in its preferences gets one and lockdownd's startup naming does not run. lockdownd's `set_device_name` (`0x1000073b0`) is the only caller of the three setters; it logs their failure and still commits, and the `SetValue DeviceName` handler ignores the result, so a host rename reports success and the name stays. A rename to the pinned name passes through. The host writes the variable (UTF-8, no terminator) before each boot and removes it when the feature is off; 1–255 bytes of valid UTF-8 without control characters, otherwise off. Interposing works because both daemons are standalone images. Ships with `system-launchdaemons-boot-environment`; takes effect at the next boot. Details: `Research/Guest/device_name_pinning.md`. **Not yet run on a guest**: NVRAM readability from both daemons, and whether Settings renames through lockdownd, are open. | Y | Y | Y |
### Swift port status — the eight DSC patchers (2026-09-23)
@@ -2788,3 +2789,7 @@ DeviceTree are also in Preboot and could follow the same path later.
## Optional Settings row hiding (WIP, 2026-10-07)
Two standard-blocked declarations hide Apple Account, Game Center, iCloud and Wallet in Preferences (`system-preferences-exp-root_rows`) and Software Update in GeneralSettingsUI (`dyld-exp-settings_software_update_row`). Native discovery is restricted to reviewed 24A435 inputs. The installer uses pristine executable backups and cache undo records with page re-attestation. All five rows passed guest rollback, reapplication and reboot checks. See [research report](Guest/2026-10-07_reverse-settings-rows-report.md). Broader firmware coverage and bundled deployment remain WIP; no kernel/SEP or runtime hook changes are included.
+
+## Pinned guest device name (2026-10-07)
+
+Row 27. `libdevicename.dylib` makes configd publish the name the host writes to NVRAM `vphone-device-name` as the device name, and makes lockdownd refuse renames to anything else; without the variable it passes everything through. It is the first library a process receives beside another: lockdownd already took `libmisfix.dylib`, so `vpInsertedLibrariesFor` in `Shared/InjectionEnvironment.h` now returns every installed library for a path and `vpInsertHookLibraries` adds each one an environment lacks. Single-library targets and their spawn log lines are unchanged. `preferences.plist` is never written: the pin is applied to configd's `SCDynamicStoreSetMultiple` publication, because the `SCPreferencesGetValue(kSCPrefSystem)` it flattens is also read and written back on configd's model-change path. Static analysis only so far; see `Research/Guest/device_name_pinning.md` for the flow, the assumptions still to confirm and the verification steps.
diff --git a/Research/Guest/device_name_pinning.md b/Research/Guest/device_name_pinning.md
new file mode 100644
index 00000000..8265d3f6
--- /dev/null
+++ b/Research/Guest/device_name_pinning.md
@@ -0,0 +1,166 @@
+# Device name pinning
+
+The host can give a guest a fixed device name, the one Xcode's DeviceHub,
+`devicectl`, Finder and the guest's own Settings show, and keep it from being
+renamed inside the guest. This note covers the guest half:
+`libdevicename.dylib`. The host half writes the NVRAM variable it reads.
+
+Static analysis of the iOS 27.0 (24A435) `configd` and `lockdownd` from an
+`iPhone17,3` guest, 2026-10-07. Addresses are from those binaries. Status: not
+yet run on a guest; see [Verification](#verification).
+
+## Where the name lives
+
+The device name is `System/System/ComputerName` in
+`/private/var/preferences/SystemConfiguration/preferences.plist`. Nothing reads
+it from there directly. configd publishes it into the dynamic store, and every
+reader goes through the store:
+
+```text
+preferences.plist ── configd PreferencesMonitor ──> Setup:/System { ComputerName, ComputerNameEncoding }
+ │
+ SCDynamicStoreCopyComputerName ─────────────────┤
+ lockdownd copy_device_name (lockdown GetValue DeviceName: Finder, Xcode, devicectl)
+ MobileGestalt UserAssignedDeviceName, UIDevice.name
+```
+
+configd's `updateConfiguration` (PreferencesMonitor, statically linked into
+`/usr/libexec/configd`; `0x100062098`…) does the publishing:
+
+1. `SCDynamicStoreCopyMultiple(store, NULL, ["^Setup:.*"])`: what the store has.
+2. `SCPreferencesCopyKeyList`, then `SCPreferencesGetValue(prefs,
+ kSCPrefSystem)` flattened from `/` into `Setup:/…` keys (`0x100064578`), so
+ `System/System` becomes `Setup:/System`. The current set is flattened the
+ same way.
+3. Keys whose value did not change are dropped; keys that disappeared are
+ collected for removal.
+4. One `SCDynamicStoreSetMultiple(store, keysToSet, keysToRemove, NULL)`
+ (`0x100062c04`).
+
+Renames come in through lockdownd's `set_device_name` (`0x1000073b0`):
+`SCPreferencesCreate("com.apple.mobile.lockdown")`, `SCPreferencesLock`,
+`SCPreferencesSetComputerName(prefs, name, kCFStringEncodingUTF8)`,
+`SCPreferencesSetHostName` and `SCPreferencesSetLocalHostName` with a sanitized
+name, `SCPreferencesCommitChanges`, `SCPreferencesApplyChanges`. These are
+lockdownd's only callers of the three setters. A failing setter is only
+logged, and the function still commits. It has two callers:
+
+- startup (`0x100011ec0`): when `copy_device_name` finds no name, lockdownd
+ names the device after `MarketingDeviceFamilyName`;
+- the lockdown `SetValue DeviceName` handler (`0x10001ed7c`), which ignores
+ the result. The host's rename (Finder, `idevicename`) arrives here.
+
+## The channel
+
+Before every boot with the feature on, the host writes NVRAM variable
+`vphone-device-name`: the name's UTF-8 bytes, no terminator. With it off, the
+host removes the variable. The guest reads it once per process as the
+`IODeviceTree:/options` property of that name, then under Apple's NVRAM GUID
+(`7C436110-…:vphone-device-name`) if the bare name is absent.
+
+The value must be 1 to 255 bytes of valid UTF-8 with no control characters;
+trailing NULs are dropped, and a CFString is accepted as well as CFData. Any
+other value means the feature is off and the library passes every call
+through.
+
+## configd: publishing the pinned name
+
+`SCDynamicStoreSetMultiple` is interposed. For a call that sets or removes
+anything under `Setup:`, which in configd is the preferences monitor,
+`Setup:/System` is rewritten so its `ComputerName` is the pinned name and its
+`ComputerNameEncoding` is UTF-8. Other entries stay.
+
+- The call sets `Setup:/System`: its value is pinned.
+- The call leaves it out because it did not change: the store's current value
+ (`SCDynamicStoreCopyValue`) is pinned and added if it names anything else.
+ This covers a first boot whose preferences have no name: the store gets one
+ anyway, so lockdownd's startup naming finds a name and does not run.
+- The call removes it: the removal is dropped and a value holding the pinned
+ name is set instead.
+
+`SCDynamicStoreSetValue("Setup:/System", …)` is pinned the same way. No configd
+caller is known to set that key directly.
+
+The pin is applied when configd publishes, not when it reads the
+preferences. Replacing what `SCPreferencesGetValue(prefs, kSCPrefSystem)`
+returns would reach the same flattening, but the monitor's model-change path
+(`sub_10006155c`) reads that value and writes it back with
+`SCPreferencesSetValue` around `__SCNetworkConfigurationSaveModel`, which
+would commit the pinned name to disk. Applied at publication, it never
+reaches `preferences.plist`: the file keeps the guest's own name, and turning
+the feature off brings that name back at the next boot.
+
+Not pinned: `LocalHostName` and the DNS host name, which are separate keys
+derived from the name when it is set; set-hostname's
+`__SCPreferencesCopyComputerName` (`0x100049fcc`), which reads the file
+directly to decide a DNS host name after a reverse lookup.
+
+## lockdownd: refusing renames
+
+While a name is pinned, `SCPreferencesSetComputerName` with any other name
+returns false and sets `kSCStatusAccessError` (`_SCErrorSet`, exported by
+SystemConfiguration). The host name and local host name setters that follow on
+the same preferences object are refused too, so the commit changes nothing.
+A rename to the pinned name itself goes through.
+
+Because `set_device_name` and its `SetValue` handler ignore the failures, a
+host that renames the guest is told it worked, and the name stays.
+lockdownd logs `SCPreferencesSetComputerName failed (…): Permission denied`.
+
+## Injection
+
+Both spawn hooks insert `/usr/lib/libdevicename.dylib` into
+`/usr/libexec/configd` and `/usr/libexec/lockdownd` (`vpIsDeviceNameTarget` in
+`Shared/InjectionEnvironment.h`). lockdownd also takes `libmisfix.dylib`, so
+`vpInsertedLibrariesFor` returns every library for a path and lockdownd starts
+with
+`DYLD_INSERT_LIBRARIES=/usr/lib/SystemHook-vphone.dylib:/usr/lib/libmisfix.dylib:/usr/lib/libdevicename.dylib`.
+A job launchd spawns itself goes through the launchd hook; one started through
+`xpcproxy` goes through SystemHook. Either way it gets both libraries, and an
+environment that already names some of them gains only the missing ones.
+
+The interposes reach configd's and lockdownd's calls because both are
+standalone images binding through their own imports. A call made inside the
+shared cache is not rebound (see "An interpose does not cross the shared
+cache" in `0_binary_patch_comparison.md`). The library checks
+`getprogname()` and acts only in configd or lockdownd.
+
+The library ships with `system-launchdaemons-boot-environment`. configd and
+lockdownd pick it up when they next start, which in practice is the next boot.
+
+## Assumptions to confirm
+
+- Root processes can read `vphone-device-name` from `IODeviceTree:/options` as
+ the host writes it, bare or under the GUID.
+- lockdownd can read it too. If it cannot, renames reach `preferences.plist`,
+ but configd still publishes the pinned name.
+- PreferencesMonitor is the only publisher of `Setup:/System`.
+- Settings' General → About → Name goes through lockdownd. If Settings writes
+ the preferences itself, it is not refused, but configd still publishes the
+ pinned name.
+- configd starts after `/private/var` is mounted, so its log lines are kept.
+ The pin does not depend on the log.
+
+## Verification
+
+On a test VM with the host writing a name, for example `Lab Phone`:
+
+1. `/var/mobile/Library/Caches/vphone-launchdhook-injection.log` or
+ `vphone-systemhook-spawn.log` shows `inserted+devicename` for configd and
+ `inserted+misfix+devicename` for lockdownd.
+2. `/var/mobile/Library/Caches/vphone-devicename.log` has
+ `configd pinned name "Lab Phone"` and `published Setup:/System ComputerName
+ "Lab Phone"`.
+3. `ideviceinfo -k DeviceName`, `xcrun devicectl list devices` and DeviceHub
+ show `Lab Phone`. So does Settings → General → About.
+4. `idevicename Other` returns, and `ideviceinfo -k DeviceName` still says
+ `Lab Phone`. The log has `lockdownd refused
+ SCPreferencesSetComputerName("Other")`. `preferences.plist` keeps the name
+ it had before.
+5. With the variable removed and the guest rebooted, the guest's own name is
+ back and renames work again.
+
+Host-side checks need no guest: `make -C VPhoneGuestComponents
+test-injection-environment test-devicename` covers target matching,
+lockdownd's two libraries, the NVRAM value's decoding, the publication
+rewrite and the rename decision.