Files
UniXNU Docs 7da8bb924d docs: describe arm64 user PAC keys and in-process AppSync signing
The arm64e porting page covers the EL0 key state of arm64 processes and the
shared region key value. The security page and the AppSync README describe the
signer library inside installd, the platform status exec clears for AppSync
apps, and the device state.
7da8bb924d · 2026-11-08 21:32:39 +08:00
History
..

AppSync adapter for UniXNU

The sheng iPadOS 27.0.1 (24A446) adapter applies to all user application bundles, including unsigned, fakesigned and expired packages. Applications and updates are installed on device without a build-time list or image rebuild.

It follows AppSync Unified's separation of installation validation, FrontBoard launch trust and the LSApplicationWorkspace installer. Upstream authors: Karen/あけみ and Linus Yang. The Objective-C adaptation is GPL-3.0-or-later. This is an independent UniXNU port. On sheng, an unsigned arm64 app installs over USB, launches and stays installed across reboots.

Install applications

Build and boot the sheng 24A446 image with its original Data seed and firmware inputs. The board selects payload.runtime.appsync = true and appsync=1. There are no per-application build options. Transfer any compatible IPA to the device, then run:

/usr/libexec/unixnu-appinst /path/on/device/Example.ipa

Other installers using MobileInstallation use the same hooks. The optional older syntax unixnu-appinst BUNDLE_ID FILE.ipa also works. The tool gives the native installer a private copy so it cannot consume the supplied IPA. Installation is not started automatically by boot or packaging. Existing apps with usable signature structures are covered after boot without a general reinstall. Truly unsigned or structurally damaged code needs the installation repair path before launch.

Installation and signature repair

AppSync.m hooks MICodeSigningVerifier in installd and MobileInstallationHelperService. It enables native ad-hoc signing, disables preloaded trust-cache and online authorization requirements, and skips profile ID validation for every .app tree on Data (/private/var/ or /var/). This includes installation staging, embedded frameworks and extensions. Original options are restored on success, failure and exceptions.

Signing.m first invokes the original verifier. If it rejects a user package, the adapter locks that bundle, preflights its Mach-O slices, removes obsolete embedded provisioning profiles, and signs the bundle recursively with the signer library inside installd, whose sandbox denies process-fork. The signer preserves existing XML/DER entitlements, regenerates code and resource signatures, and marks signatures without a CMS identity as ad-hoc. The original verifier then validates the result and creates native signing information. Valid packages remain unchanged. Concurrent repairs serialize on the bundle; a failed signer or second validation remains an installation failure.

The signer is Procursus ldid, with the small ldid-adhoc.patch required by this AMFI path. signer-sources.json pins its source and the static OpenSSL/libplist dependencies by commit and archive SHA-256. signer.py builds /usr/lib/libunixnu-ldid.dylib, an arm64e iOS library with only libSystem and libc++ dynamic dependencies that exports unixnu_ldid_sign_bundle. ldid-library.cpp runs ldid's -Hsha256 -M -S on a bundle, resets ldid's option state before each call, serializes calls and returns ldid's exit() as an error. The patch also memory-maps each signed file, which keeps large applications within installd's memory limit, and signs Extensions/ ExtensionKit bundles as nested code, like PlugIns/. Build downloads are cached; on-device signing is offline. Licenses accompany the runtime; the cache retains ldid objects and static libraries for relinking. See LICENSE and the pinned upstream sources.

Malformed Mach-O commands, encrypted slices and symlinks escaping the bundle are rejected before repair. This port does not decrypt FairPlay content or supply App Store account authorization; packages still need executable code compatible with the target OS and CPU.

Launch and kernel trust

FrontBoard's FBSSignatureValidationService trustStateForApplication: returns its trusted state (8) for all user bundles. Every hook checks the private method ABI before activation. System bundle paths retain native behavior.

The sheng-appsync-user-trust.patch calls appsync_trust_user_code from ubc_cs_blob_add, after XNU validates the signature structure and computes the CodeDirectory hash and before AMFI verifies it. The kernel adds that hash using the engineering trust-cache interface already used for owner boot modules. New applications, updated executables and nested libraries are handled on demand. VM page hashes and AMFI callbacks still run. No client can submit an arbitrary hash through a user-accessible registration API.

Registration deduplicates under the trust runtime lock and retains successful modules until reboot. The next boot registers an app again on first mapping. There is a 65536-module memory bound per boot; allocation/load failures are reported and reject the mapping. Like other trust-cache entries, registration trusts the same code hash for the rest of that boot, even if its file moves. Trust-cache membership makes AMFI report the code as a platform binary; right after load_machfile, exec clears that status for a user .app main executable, so the app runs as an ordinary third-party process. appsync=0 disables both runtime mounts and automatic registration.

Packaging and verification

build.py pins the three original 24A446 executable inputs. It routes their Foundation dependency through the signed adapter, which re-exports Foundation, preserving ordinals, code addresses and chained/PAC fixups. Native identifiers and entitlements are checked after signing. The boot trust bundle includes these runtime copies and the signer library; user application hashes are not build inputs. appsync-service.json records scope = "all-user-bundles", dynamic_user_trust = true, signature_repair = true and the source pins.

From UniXNU on macOS with Xcode and Python 3.13 or later:

python3.13 scripts/appsync/test.py --signing --os-root /readonly/24A446/OS \
  --os-image /path/to/24A446/OS.dmg
python3.13 scripts/test-runtime-inputs.py

The host suite runs production hooks and repair code under ASan/UBSan. It checks unknown apps/updates, nested bundles, unsigned and multi-architecture Mach-O files, non-Apple and expired certificate fixtures, resource/profile repair, entitlement preservation and rejected encrypted/escaping inputs. Repaired outputs are independently checked with Apple's codesign tool. The first iOS certificate rejection is modeled on the host.

The exact kernel registration source is extracted from the board patch and compiled with a mock trust runtime to test concurrent deduplication, updates, frameworks, disabled behavior and allocation/load failures. Full kernel and image builds separately check the real XNU declarations and linkage. Runtime packing tests verify original trust-module and Data preservation and repeat builds.