Skip to content

Minimal: Runtime Cryptex Support via the trusted darwinOS environment - #900

Merged
0xJacky merged 6 commits into
Lakr233:mainfrom
mpass99:feature/trusted-darwinos-cryptex
Nov 12, 2026
Merged

0xJacky merged 6 commits into
Lakr233:mainfrom
mpass99:feature/trusted-darwinos-cryptex

Conversation

@mpass99

@mpass99 mpass99 commented Nov 11, 2026

Copy link
Copy Markdown
Contributor

Supersedes #344

Why

A minimal guest is a resealed system on a stock boot chain, kernel and TXM. Nothing may write the System volume after the restore, so every change to what runs in the guest means building a new restore image and restoring again.

cloudOS solves this with cryptexes: signed disk images that cryptexd mounts at runtime with their own trust cache. They only work in the trusted darwinOS environment, and no vphone restore had ever asked for it.

#344 got there by restoring through MobileDevice. The real difference between the two restores turned out to be one TSS tag.

What

One opt-in patch, filesystem-exp-trusted_darwinos, only for minimal iPhone/iPad guests. Launchpad shows it as the Trusted darwinOS environment box (feature trusted-darwinos) directly on New Machine's Patches page, with its summary below it, and in Patch Settings….

Where Change
Restore Sends the build identity's Ap,OSEnvironment in the AP TSS request, as Apple's host does. libtatsu's fixed tag list leaves it out; libimobiledevice/libtatsu#14 fixed that upstream (merged 2026-11-11), but the AppleMobileDeviceLibrary build vphone-cli pins predates it, so the restore adds the tag itself until the pin moves. fw prepare drops the tag from the hybrid identity; the patch writes 0x06 back. iBoot then applies /osenvironments/trusted-darwinos.
Static trust cache In environment 6, AMFI enforces Restricted Execution Mode. cryptexctl copies Apple's base entries with flags 0x00 beside its own 0xC0 ones. The rebuild keeps one entry per CDHash, allowed in both phases; without this, launchd is killed.
System /usr/bin/cryptexctl from the cloudOS OS image, staged by fw prepare and cached per cloudOS build. WKMS refuses the cloudOS key at times (403 on 2026-11-10/11, ipsw fw aea too, while iOS keys worked); then fw prepare restores cloudOS in a temporary VM, as it does for the GPU driver, and copies cryptexctl off its System volume.
launchd.plist Without com.apple.mobile.NRDUpdated. TXM's environment-6 policy checks every trust cache load against the SEP's digest, and the recoveryOS update brain's cache fails it with a panic (TXM [Panic]: [code: 0x000000F3 | 4]). These were the "panics from time to time" in #344.
vphoned cryptex.list, cryptex.install (cryptexctl personalize --host-identity, then install; with persist: true vphoned keeps the cryptex and installs it again, one at a time, when it starts after a reboot), cryptex.uninstall; capability cryptex.
VM window Apps › Install Cryptex… builds a cryptex from a folder with cryptexctl.research, mounted at /private/var/DarwinDataCenterSupportImage/<identifier>, uploads it and installs it. Several at once. It also takes a .cxbd made for vresearch101; an SRD cryptex (cryptexctl create --research) is refused before upload with a note to choose its folder. List Cryptexes.
VM window, environment A guest with none of vphone's environment libraries (minimal) is no longer sent them on each connection. The upload and the failing remount ran again on every reconnect, and on an iOS 26.5 trusted darwinOS guest the agent dropped during the upload, so it never settled (245 reconnects on one test VM, and a cryptex upload cut off). Now a few reconnects while it boots, then none.
Launchpad Features get boxes of their own on New Machine's Patches page, with their summary. The build's patch overrides are recorded before fw prepare, so it knows the box is on.

Effects:

  • REM is enforced.
  • The box only takes effect with a restore.
  • Personalization needs network.

A separate commit makes cryptexes persist through vphoned rather than cryptexctl --persist (see Validation for why). Another retries the AppleDB catalogue and WKMS key fetches. Both failed often on one host (-1005 in bursts), which cost whole fw prepare/fw patch runs.

Details, disassembly and REM flag table: Research/Firmware/trusted_darwinos_cryptexes.md.

Validation

iPhone17,3 26.5 (23F77) / cloudOS 26.5 (23F75), minimal with the box on, created with Launchpad vm create --no-template:

  • Requesting Ap,OSEnvironment = 6; TSS signed it; restore succeeded.
  • AMFI took its environment-6 path; there was no launchd kill; first boot and vphoned passed. developer_mode.status reported enabled: false.
  • cryptex.install of a cryptexctl.research create cryptex: personalized by Apple's TSS, mounted at /private/var/PrivateCloudSupportInternalAdditions, and its file was readable there.
  • NRDUpdated panic: reproduced without the fix (within about 10 minutes of runtime with network). With the fix: NRDUpdated not running, no panic over 13 minutes awake with network (one boot session), with three cryptex installs and two uninstalls. cryptexd's trust cache load of a test cryptex logs TXM errors (selector: 12 | 0x03 | 0xA3), not a panic.
  • cryptexctl with the WKMS key refused (403): fw prepare restored cloudOS in a temporary VM and staged cryptexctl, byte-identical to the one ipsw fw aea extracts; the next machine reused it from the cache.
  • cryptex.uninstall: cryptexctl exits 1 without output after an uninstall that worked; the RPC now judges by cryptexctl list.
  • Install Cryptex… with the folder of the SRD barebones-cryptex example (build/<id>.root): installed. Its .cxbd (SRD format) failed in the guest, hence the check before upload. Its launch daemon, the example's server Mach-O, started from the cryptex and answered on port 7070.
  • Several cryptexes (iOS 18.6 / cloudOS 18.6 guest): the kernel's sandbox profile (file-mount) lets cryptexd mount only at PCC's cryptex paths, /private/var/DarwinDataCenterSupportImage with its subpaths among them. Three cryptexes at three such paths, and two at …/DarwinDataCenterSupportImage/<id>, mounted at once, each personalized by Apple's TSS separately; a path outside the list fails hdi_mount with EPERM.
  • iOS 26.5 / cloudOS 26.5, fresh guest: /private/var/DarwinDataCenterSupportImage does not exist, so Install Cryptex… creates it; then two cryptexes at …/<id> mounted at once.
  • Persistence: with cryptexctl's own --persist, one persisted cryptex came back after a reboot, but with two, 3 of 12 boots panicked in TXM (0xF3 | 4, cryptexd): cryptexd reinstalls them in parallel at boot, and the panic came when one image was validated before the other's trust cache had loaded. So vphoned keeps cryptexes installed with persist: true itself and installs them again one at a time when it starts, with the kept ticket (Apple's signing server again only if that is refused); all cryptexctl runs share one serial queue. With two such cryptexes: 18 reboots and one cold start, no panic, both mounted 16–27 s after boot each time, launch daemon answering; after cryptex.uninstall neither came back.
  • The trusted darwinOS environment also works with iOS 18.6 / cloudOS 18.6 (cryptexctl came from the cloudOS restore fallback).
  • Manual: new page Documents/<lang>/machines/cryptexes.md (en, zh, ja, ko).
  • Tests, on the branch rebased onto d1c36fa: FirmwarePatcherTests (the suites touched here, Trust cache and Cryptex file operations, pass; the failures all need reference files under ipsws/), run-methods-tests.sh (201 names, 0 failures), ResultSchema (85/85), the vphoned session, health and process tests, and all 12 Launchpad test scripts. run-logic-tests.sh does not compile on main either: LogicTests.swift:885 calls MethodSpec() without the now-required summary.
  • The zh/ja/ko pages and catalogue strings are mine and still need the usual translation review.

mpass99 and others added 3 commits November 11, 2026 16:53
Both are one HTTPS GET whose failure loses a whole `fw prepare` or `fw patch`.
On a 2026-11-10 host, about half of back-to-back fetches of the AppleDB
catalogue (Cloudflare, HTTP/3 offered) failed with
NSURLErrorNetworkConnectionLost, up to six in a row, while each try after a
pause of a second or two succeeded; curl never failed. The WKMS key fetch
failed the same `fw prepare` once with a server error. Retry dropped
connections, timeouts, 429 and 5xx a few times, a little longer apart each.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Port of Lakr233#344's cryptex support to the current tree. Opt-in for minimal on
iPhone and iPad: the patch filesystem-exp-trusted_darwinos, offered as the
"Trusted darwinOS environment" box (feature trusted-darwinos).

- Restore: send the build identity's Ap,OSEnvironment in the AP TSS request,
  as Apple's host does (libtatsu's fixed tag list leaves it out). fw prepare
  drops the tag from the hybrid identity; the patch writes 6 back.
- Trust cache: in environment 6 AMFI enforces Restricted Execution Mode.
  cryptexctl copies Apple's base entries with flags 0, beside its own 0xC0
  ones, so keep one entry per CDHash, allowed in both phases.
- cryptexctl: staged from the cloudOS OS image by fw prepare, cached per
  cloudOS build, and added to the merged system at /usr/bin. WKMS refuses
  cloudOS keys at times (403, ipsw fw aea included, while iOS keys work);
  with the box on, fw prepare then restores cloudOS in a temporary VM, as
  for the GPU driver, and copies cryptexctl off its System volume. That
  recovery takes cryptexctl whenever it runs.
- NRDUpdated: left out of launchd.plist. TXM's environment-6 policy checks
  each trust cache load against the SEP's digest, and the recoveryOS update
  brain's fails it with a panic (TXM 0xF3 | 4), the "panics from time to
  time" of Lakr233#344.
- vphoned: cryptex.list, cryptex.install (personalize with --host-identity,
  then install), cryptex.uninstall (judged by cryptexctl list: cryptexctl
  exits 1 silently after an uninstall that worked); capability cryptex.
- VM window: Apps > Install Cryptex… builds a cryptex from a folder with
  cryptexctl.research, uploads it and installs it; List Cryptexes. The kernel's
  sandbox profile (file-mount) lets cryptexd mount only at PCC's cryptex
  paths; each cryptex goes to
  /private/var/DarwinDataCenterSupportImage/<identifier>, one of them with
  its subpaths, so several are installed at once. A .cxbd
  is installed as it is only if it is a Cryptex1 cryptex for vresearch101;
  an SRD cryptex (cryptexctl create --research) is refused before upload
  with a note to choose its folder.
- Manual: Documents/<lang>/machines/cryptexes.md.
- VM window, environment update: a guest with none of vphone's /usr/lib
  libraries (minimal) is left alone. Every connection uploaded all of them
  and failed the remount; on an iOS 26.5 trusted darwinOS guest the agent
  dropped during the upload, so the reconnections never ended.
- Launchpad: features get their own boxes on New Machine's Patches page,
  with their summary. The build's patch overrides are recorded before
  fw prepare, which stages what they need.

Developer Mode stays off on research-board guests: AMFI enables it in
environment 6 only in its research build, and the kext mix takes AMFI from
the release kernel. Research/Firmware/trusted_darwinos_cryptexes.md has the
details and the validation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
cryptexctl install --persist leaves the reinstall at boot to cryptexd, which
installs persisted cryptexes in parallel. With two of them, 3 of 12 boots of a
trusted darwinOS guest panicked TXM (0xF3 | 4) when one image was validated
before the other's trust cache had loaded.

cryptex.install with persist: true now keeps the uploaded .cxbd, its
personalized copy and the variant under /var/db/vphoned/cryptexes, and vphoned
installs the kept cryptexes again in turn when it starts: with the kept ticket,
or personalized again if cryptexd refuses it. Every cryptexctl run goes through
one serial queue. cryptex.list reports the kept identifiers as persisted, and
cryptex.uninstall forgets them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@0xJacky

0xJacky commented Nov 12, 2026

Copy link
Copy Markdown
Collaborator

Not merged in this round. It works on the pair you tested, but it panics on first boot with the catalog's default firmware for this device, and it now needs a small change after #892.

Tested on a 2.16.1 build of this branch merged with the other open PRs, including its Launchpad (macOS 27.2 host, M5 Pro), with vm create --preset minimal --allow filesystem-exp-trusted_darwinos --no-template.

iPhone17,3 iOS 26.5 (23F77) / cloudOS 26.5 (23F75): works.

  • The WKMS key was refused here too, and the temporary cloudOS restore staged cryptexctl. It requested Ap,OSEnvironment = 6 and was signed.
  • The guest restored with Ap,OSEnvironment = 6 and passed first boot.
  • cryptex.list answered and developer_mode.status reported enabled: false.
  • No panic in the time it ran.
  • I could not test cryptex.install: this host has no cryptexctl.research.

iPhone17,3 iOS 27.0.1 (24A446) / cloudOS 26.4 (23E5207q), the catalog default: first-boot panic.

libignition: 1:   os environment      : trusted-darwinos
libignition: 1: cryptex1 sniff: detecting cryptex1 directory
libignition: 1: cryptex1 sniff: ignition failed: 8
dyld[1]: result from check_np(): -1, errno 12
dyld[1]: dyld cache '(null)' not loaded: syscall to map cache into shared region failed
dyld[1]: Library not loaded: /usr/lib/libSystem.B.dylib
panic(cpu 1 caller …):  initproc failed to start -- exit reason namespace 6 subcode 0x1 description: Library not loaded: /usr/lib/libSystem.B.dylib

The box sits on New Machine's Patches page, so a user who ticks it with the default firmware gets this panic after a full restore. Before merging, please either make it work on 27.x, or refuse or explain the combination before the restore starts (for example, from the IPSW's major version), and say which pairs work in Documents/*/machines/cryptexes.md.

After #892 (merged), every GuestMethod enum lives in a dependency-free GuestAPI<Area>Methods.swift file that the methods harness compiles. run-methods-tests.sh reports cryptex.install/list/uninstall has no harness cell until CryptexMethod moves, unchanged, into VPhoneDaemon/Daemon/GuestAPICryptexMethods.swift. With that move and the cryptex.* rows in the catalog, the methods tests pass (201 names, 0 failures). Merging main also conflicts in Research/0_binary_patch_comparison.md (keep both sections) and methods-catalog.tsv (keep main's typed cells and add the three cryptex.* rows).

Also checked: with the box off, a standard iPhone17,3 27.0.1 restore with this branch restored and booted as before.

0xJacky and others added 3 commits November 12, 2026 16:12
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Since Lakr233#892 every GuestMethod enum lives in a dependency-free
GuestAPI<Area>Methods.swift file that the methods harness compiles; without
the move run-methods-tests.sh reports the cryptex.* rows as having no
harness cell.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
iOS 27.0.1 with cloudOS 26.4 restores in environment 6, then dyld cannot
mount the OS cryptex ("cryptex1 sniff: ignition failed: 8"), maps no shared
cache, and launchd panics on libSystem. iOS 26.5 with cloudOS 26.5 boots.
fw prepare now refuses the patch for iOS 27 and later right after resolving
the IPSWs, and the patcher refuses it before adding cryptexctl when the box
was turned on after fw prepare. The manual says which versions work.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@0xJacky
0xJacky merged commit 6f57024 into Lakr233:main Nov 12, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants