ios3ds images come "pre-jailbroken" the way greenpois0n or redsn0w left an iOS 4.2.1
device: Cydia on the home screen, working dpkg/APT, and the base system Cydia
treats as essential. Code signing is already off in our boot-args
(amfi_allow_any_signature=1 cs_enforcement_disable=1), so nothing else is needed
for unsigned code to run.
The packages are Saurik's (Telesphoreo). They are never committed and never in a
release zip. make sd and the installer download them on your machine from the
original repository, check every file against a pinned sha256, and unpack them
into the rootfs image. Without network the image is built without Cydia (one
warning line), never fails.
rootfs/cydia.json pins 35 packages: Cydia and the closure of its Depends/
Pre-Depends, plus every Essential: yes package, each at the newest version in
http://apt.saurik.com/ dists/tangelo-3.7 (identical to the ios dist; .deb
files redirect to cache.saurik.com). 6.5 MB download, about 40 MB unpacked
(the volume has ~400 MB free after it).
| Package | Version | Package | Version | |
|---|---|---|---|---|
| cydia | 1.1.30 | dpkg | 1.18.10-12 | |
| cydia-lproj | 1.1.12 | apt7 / apt7-lib / apt7-key | 0.7.25.3-9 / -16 / -3 | |
| base | 1-4 | bash | 4.0.44-16 | |
| coreutils / coreutils-bin | 8.12-13 / 8.12-9 | debianutils | 3.3.3ubuntu1-1p | |
| darwintools | 1-5 | uikittools | 1.1.12 | |
| system-cmds | 433.8-14 | shell-cmds | 118-7 | |
| firmware-sbin | 0-1 | profile.d | 0-2 | |
| sed, grep, findutils, diffutils | 4.1.5-8, 2.5.4-3, 4.2.33-7, 2.8.1-6 | tar, gzip, bzip2, lzma | 1.29-10, 1.6-7, 1.0.5-8, 4.32.7-5 | |
| gnupg, berkeleydb | 1.4.8-4, 4.6.21-5 | ncurses, readline | 5.7-15, 6.0-8 | |
| pam, pam-modules | 32.1-4, 36.1-5 | org.thebigboss.repo.icons | 1.0 | |
| mobilesubstrate (Cydia Substrate) | 0.9.6301 | com.saurik.substrate.safemode | 0.9.6001 | |
com.skyglow.tlsfix (TLSFix, from GitHub, group tlsfix) |
1.3 |
Why these versions: Cydia 1.1.30 (2017) is the last release and still has an
armv6 slice with LC_VERSION_MIN_IPHONEOS 2.0; it links only libraries 4.2.1
has (libstdc++, WebKit/WebCore, SpringBoardServices, ...). Every Mach-O in the set
was checked to have an armv6 or generic-ARM slice. The 2011 package versions a
greenpois0n bootstrap installed are no longer all served, and an old Cydia would
immediately offer these upgrades anyway.
Also installed: Cydia Substrate 0.9.6301 (mobilesubstrate, the last
Telesphoreo release; armv6 slices, LC_VERSION_MIN_IPHONEOS 2.0) and its
Substrate Safe Mode 0.9.6001, and the TLSFix 1.3 tweak (TLS 1.2/1.3 for
iOS, certificates.md section 4) from
github.com/ObscureMosquito/TLSFix/releases (entry with its own url and
"group": "tlsfix": left out with TLSFIX=0 / --no-tlsfix / IOS3DS_TLSFIX=0 /
recipe "tlsfix": false; if only its download fails, the image is built without
it). How Substrate gets into processes on
ios3ds is not how Substrate does it itself, see the next section.
What Substrate 0.9.6301 would do. Its extrainst_ (a Mach-O, not run here)
appends bsexec .. /usr/bin/cynject 1 .../SubstrateLauncher.dylib to
/etc/launchd.conf (or links /etc/rc.d/substrate for jailbreaks with an rc.d
untether). 4.2.1's launchctl reads /etc/launchd.conf at boot and waits for each
bsexec, so no untether is needed: cynject (task_for_pid(1), allowed by our
boot-arg amfi_unrestrict_task_for_pid=1) loads SubstrateLauncher.dylib into
launchd, which hooks posix_spawn and adds DYLD_INSERT_LIBRARIES= /Library/MobileSubstrate/MobileSubstrate.dylib to everything launchd starts.
On 4.2.1 this hangs the boot: cynject returns 0, launchd forks its ~38 jobs,
and every one of them blocks for good (QEMU: no daemon ever execs, CPU idle; the
children's last system calls are kill/waitpid from the hook's helper-process
path). Putting the same DYLD_INSERT_LIBRARIES into launchd's global environment
(setenv in /etc/launchd.conf, how pre-2011 MobileSubstrate worked) also hangs
the boot. Not debugged further (Substrate is closed source).
What ios3ds does instead (rootfs/cydia.json substrate, applied by
cydia.substrate_setup after the recipe):
| Process | How Substrate gets in | Our own library |
|---|---|---|
| SpringBoard | its launchd plist inserts /usr/lib/ios3ds-applog.dylib; applog's constructor dlopens MobileSubstrate.dylib (as for apps, below) |
ios3ds-applog |
| every app | SpringBoard inserts /usr/lib/libgmalloc.dylib (= ios3ds-applog, SBGuardMallocAlways) into each app, replacing anything else; ios3ds-applog's constructor dlopens MobileSubstrate.dylib in executables inside a .app (after adding it to DYLD_INSERT_LIBRARIES, where Substrate's loader looks for and removes itself) |
ios3ds-applog |
| ios3ds-nettest | dlopen after it loads CFNetwork (TLSFix filters on CFNetwork) |
|
| configd, securityd, other daemons | none (nothing targets them; it would only cost memory) | configd: Wi-Fi bridge interposer; securityd: AES interposer (unchanged) |
sandboxed apps (MobileSafari with its built-in MobileSafari profile, App Store apps) |
none: the sandbox refuses every file under /Library (open gives EPERM for /Library/MobileSubstrate/..., /Library/Frameworks/CydiaSubstrate.framework/..., and for /var/mobile/Library/ConfigurationProfiles), so the dlopen fails and the app runs without tweaks |
ios3ds-applog (it is in /usr/lib, which the profile allows) |
No launchd plist names MobileSubstrate.dylib (substrate.daemons is empty;
cydia.substrate_setup can still append it to listed recipe jobs): a
(re)installed mobilesubstrate's extrainst_ removes that entry from the
LaunchDaemons plists, which in QEMU left SpringBoard without Substrate after a
reboot. Loading it from applog survives that. Without Cydia (CYDIA=0) nothing
changes.
Inside a process, MobileSubstrate.dylib (= SubstrateInjection.dylib) loads
SubstrateLoader.dylib only if CoreFoundation is loaded, and the loader then loads
each /Library/MobileSubstrate/DynamicLibraries/*.dylib whose plist filter
matches (Bundles / Executables / Classes / CoreFoundationVersion). Installed
extensions: MobileSafety (safe mode, SpringBoard) and tlsfix (any process with
com.apple.CFNetwork; TLSFix itself skips SpringBoard, launchd, lockdownd and
securityd).
A sandboxed process (MobileSafari, App Store apps, Mail's helpers) runs under a
Seatbelt profile that denies open() of everything under /Library, so Substrate
and TLSFix can't load and Safari keeps iOS's TLS 1.0. The kernel patch
kernel/patches-sandbox.json (SANDBOX=1 / --sandbox-open / IOS3DS_SANDBOX_OPEN=1)
does what iOS 4 jailbreaks did: it hooks the Sandbox kext's sb_evaluate
(com.apple.security.sandbox 0x803cd000, Sandbox-58.12; the central bytecode
evaluator at 0x803ced98, found as the function 75 MAC-hooks funnel into, r2 =
operation index) via a shim trampoline (shim_sb_evaluate, kernel/shim/entry.S;
the branch word is computed at build time from the shim ELF symbol, since the
New-3DS work took the once-free shim+0x0C slot). It
returns allow only for the file-read operations (op 1 file*, 6-9 file-read*
and children, 11 file-search) and runs the real evaluator for everything else,
so a sandboxed app can read the dylibs under /Library while write/exec/network/
iokit/mach stay enforced. Operation indices are from the kext's operation_names
table; the patch is verified against the original push {r4,r5,r6,r7,lr} bytes.
Why it is off by default: with the patch Safari does load TLSFix, but on the
128 MB device (MEM_SIZE 0x08000000, as the real iPod2,1) MobileSafari then dies
with "The operation couldn't be completed. Cannot allocate memory" on the first
HTTPS load — even for a 1 KB page (example.com) — because TLSFix's static OpenSSL
1.1.1w (~1.9 MB text + its heap on the first handshake) does not fit in the WebKit
content process's memory budget. So the patch turns Safari's "could not establish
a secure connection" into an out-of-memory failure; it is left out by default and
kept as an opt-in for a device with more RAM or a slimmer TLS library. Cydia and
other unsandboxed apps get TLSFix without it.
Installing a tweak from Cydia must never set up Substrate's launchd injection,
which hangs 4.2.1 (on builds without the pre-installed Substrate, installing
anything that depends on mobilesubstrate hard-locked the device: Cydia installs
it and runs its extrainst_, which calls cynject 1 at once and writes it into
/etc/launchd.conf). The build therefore:
- holds
mobilesubstrateandcom.saurik.substrate.safemode(Status: hold ok installed, manifesthold) and pins their versions in/etc/apt/preferences(priority 1001): Cydia's Upgrade and installs of dependent tweaks keep the pre-installed 0.9.6301, which satisfiesDepends: mobilesubstrateincluding versioned ones such as(>= 0.9.3997); - diverts
CydiaSubstrate.framework/Commands/cynject(a local dpkg diversion in/var/lib/dpkg/diversions): the real binary iscynject.real, and in its place a guard (/usr/libexec/ios3ds-cynject) refuses pid 1 and passes every other use (e.g. cycript) to the real one. A reinstalled or newermobilesubstrateunpacks its cynject tocynject.realas well, so itsextrainst_(which injects only throughsystem("/usr/bin/cynject 1 ...")) and anybsexec .. cynject 1line in/etc/launchd.confdo nothing; - runs
com.ios3ds.substrate-guardonce at every boot (/usr/libexec/ios3ds-substrate-guard): removes cynject lines from/etc/launchd.confand/etc/rc.d/substrate, and puts the guard back if something replaced cynject without the diversion. The build itself drops any cynject line fromlaunchd.conftoo (a fresh image has none).
Safe mode: MobileSafety (filter com.apple.springboard) and the loader's
crash handlers load in SpringBoard as on a jailbroken device, so a tweak that
crashes SpringBoard should bring it back in safe mode; not exercised in QEMU.
Our interposers are plain DYLD_INSERT_LIBRARIES entries, not extensions, so
they load in safe mode too.
Hooked into scripts/mkrootfs.py right after the volume is grown and before our own
files are written (so the recipe always wins over a deb):
- Fetch: for each pinned entry,
mirrors[i] + path->build/cydia/(installer:<work>/cydia/, deleted afterwards). A cached file whose sha256 matches is reused. Any failure (offline, 404, wrong size/hash) ->[cydia] WARNING ... building WITHOUT Cydia, and the image is built as before. - Unpack each
data.tar.{lzma,gz,bz2,xz}with xpwn'shfsplus: directories (mkdir, mode), files (add+chmod, keeping setuid bits such ascydo6755), symlinks (symlink). Owners are inherited from the parent folder, which gives root for system paths andmobile(501) under/var/mobile, as dpkg would. Paths with..are refused./var,/etc,/tmpare written through/private/.... - Maintainer scripts are not run (they are iOS binaries and shell scripts);
their effects that matter are reproduced:
firmware-sbinships empty placeholders for Apple's/sbin/fsck,mount, ... (its pre/extrainst keep the stock files): the stock files are kept (keep_stock).- Cydia's postinst:
/var/mobile/Library/Cydia,/var/mobile/Library/Caches/com.saurik.Cydia(mobile-owned). - Cydia's
firmware.sh: the virtual packagesfirmware4.2.1,cy+os.ios,cy+cpu.arm,cy+model.ipod2.1,cy+kernel.darwin10.4.0,cy+lib.corefoundation550.52, and/var/lib/cydia/firmware.ver= 6. (It still runs at each boot fromcom.saurik.Cydia.Startupand re-derives them.) - No stashing:
/.cydia_no_stash. Stashing moves/Applications,/usr/share, ... to/var/stashbecause a real iPod's system partition is small; our rootfs is one 1 GiB volume, so it would only cost time and add symlinks.pam's preinst (move.sh /usr/lib/pam) is skipped for the same reason. uikittools' extrainst rebuilds SpringBoard's app cache; the image has no cache yet, SpringBoard builds it (with Cydia) on first boot.
- dpkg database:
/var/lib/dpkg/status(each control +Status: install ok installed,Conffiles:with md5s, sorted),info/<pkg>.list(/.+ every path in the deb),info/<pkg>.{md5sums,conffiles,preinst,postinst,prerm,postrm, extrainst_}, emptyavailable,updates/,triggers/; APT's/var/lib/apt/lists/partialand/var/cache/apt/archives/partial.
Sources: none are written. On its first launch Cydia sets up its default list
itself (/var/mobile/Library/Caches/com.saurik.Cydia/sources.list, with
/etc/apt/sources.list.d/cydia.list symlinked to it): apt.saurik.com ios/550.52,
BigBoss, ModMyi, ZodTTD and, for iOS 4, repo666.ultrasn0w.com, exactly as on a
2011 device. ModMyi, ZodTTD and repo666 no longer exist, so a refresh reports
errors for them; remove them in Sources > Edit.
make sd CYDIA=0/make sdimg CYDIA=0(passes--no-cydiatoscripts/mksd.py)python3 install.py --no-cydia IPSW SDIOS3DS_CYDIA=0in the environment (any build path)"cydia": falseinrootfs/recipe.json
To remove it from a built image, rebuild with one of the above. To prefetch
(e.g. before going offline): python3 scripts/cydia.py fetch.
Edit version/path in rootfs/cydia.json, then python3 scripts/cydia.py pin
re-downloads each listed deb and rewrites size and sha256. Check new Mach-Os
still carry an armv6 (or generic ARM) slice.
- Build: the hook adds 4-8 s to
mkrootfs(978 files, ~1460hfspluscalls); 32 debs + 6 virtual packages instatus. - Boot to SpringBoard as before; the Cydia icon is on the first home screen page (re-log 77).
- Cydia launches straight into its UI: no "Preparing Filesystem", no reboot request. Installed shows the 32 packages; on first launch Cydia writes its default sources.
- At boot,
com.saurik.Cydia.Startuprunsfirmware.shin the guest (bash, sed, coreutils, gssc):statusgains thegsc.*capability packages. - With Wi-Fi (
ctr-wifimodel + slirp): Cydia's refresh downloads the Telesphoreo (ios/550.52) and BigBoss package lists, the Telesphoreo sections list appears, and installingcpiothrough Cydia (APT download + dpkg in the guest) leavescpio 2.9-2p"install ok installed" with/usr/bin/cpio. emu/soak.py --cycles 10on the image after all of the above.
- HTTPS: the current root store (certificates.md) and TLSFix (TLS 1.2/1.3, EC chains) inside Cydia: Cydia's home page loads; HTTPS depictions/repositories on TLS 1.2-only servers go through the same CFNetwork path that ios3ds-nettest tested (not tried in the Cydia UI). BigBoss's HTTPS host still fails: its certificate expired on 2026-06-15 (its repository is plain HTTP).
- Dead default sources (ModMyi, ZodTTD, repo666) show errors on refresh.
- The startup daemon re-runs
firmware.shon every boot (stock behaviour); it is a few seconds of background shell work. - Substrate is not in launchd daemons (only in SpringBoard and apps): tweaks for daemons don't load.