Run a virtual iPhone on an Apple Silicon Mac.
Swift
// DyldSharedCacheLockdownModePatcher.swift — Stop libSystem's `os_lockdown_mode_enabled`
// from crashing on the vphone kernel.
//
// iOS 27's `os_lockdown_mode_enabled()` resolves Lockdown Mode once, from a
// block, via `sysctlbyname("security.mac.lockdown_mode_state_public", …)` and
// `os_crash`es when the sysctl returns -1 (`lockdown_mode.c`). The vphone base
// kernel (cloudOS 26.x) does not implement that MAC sysctl, so the call fails
// with ENOENT and every process that queries Lockdown Mode aborts — including
// launchd (pid 1), which panics the system right after "Continuing system
// boot".
//
// The block pre-zeroes its output buffer (`stp x8, xzr, [sp]`), so dropping the
// error branch makes the failure path fall through to the normal path, read 0,
// and record "Lockdown Mode disabled". On a kernel that does implement the
// sysctl the branch is never taken, so the patch is behaviour-neutral there.
//
// Shape (in `___os_lockdown_mode_enabled_block_invoke`):
//
// bl <sysctlbyname>
// cmn w0, #1 ; w0 == -1 ?
// b.eq <os_crash> ; -> NOP
//
// Anchored on the in-image local symbol; the sysctl-error idiom is located by
// control-flow shape through Capstone; the NOP comes from `ARM64.nop`; the
// modified page is re-attested through `DyldSharedCacheCodeSignature`.
//
// Port of `scripts/patchers/cfw_patch_lockdown_mode.py`, which stays the
// independent reference — `DyldSharedCacheLockdownModePatcherTests` runs the Python on one
// clone of the real cache and this on another, and compares the two byte for
// byte.
//
// One cosmetic divergence, in text only: this links Capstone 6 and the
// reference runs Capstone 5, which prints a branch target as `0x237ef22bc`
// where the older one prints `#0x237ef22bc`. That string reaches the log line
// and the `PatchRecord` description, never a patched byte, and nothing here
// matches on operand text.
import Foundation
import VPhonePatchKit
public enum DyldSharedCacheLockdownModePatcher {
// MARK: - Anchors
/// The block the sysctl lives in, under both manglings seen across
/// toolchains. The first one that resolves wins, exactly as in the Python.
public static let symbolCandidates = [
"___os_lockdown_mode_enabled_block_invoke",
"__os_lockdown_mode_enabled_block_invoke",
]
/// How far into the block to decode. The idiom sits within a dozen
/// instructions of the entry on every build seen so far; the decode also
/// stops at the block's first `ret`/`retab`, so this is only a ceiling.
static let maxInstructions = 60
/// One disassembler for the whole patcher — `ARM64Disassembler` is
/// `Sendable` and stateless across calls.
private static let disassembler = ARM64Disassembler()
// MARK: - Outcome
/// What one run did, in the terms the Python prints.
public struct Outcome: Sendable {
public enum Verdict: Sendable, Equatable, CustomStringConvertible {
/// No `os_lockdown_mode_enabled` block in this cache — a pre-iOS-27
/// userland. Not an error: the crash it guards against cannot
/// happen there.
case symbolAbsent
/// The gate already holds the NOP this patch writes. Nothing was
/// written and nothing needed re-attesting.
case alreadyPatched
/// A dry run that located a live gate and stopped short of writing.
case wouldPatch
/// The NOP was written and the page it dirtied re-attested.
case patched
public var description: String {
switch self {
case .symbolAbsent: "symbol absent"
case .alreadyPatched: "already patched"
case .wouldPatch: "would patch"
case .patched: "patched"
}
}
}
public let verdict: Verdict
/// Which of `symbolCandidates` resolved, when one did.
public let symbolName: String?
/// Address of the block the gate was found in.
public let functionVMA: UInt64?
/// Address of the branch that was (or would be) NOPed.
public let gateVMA: UInt64?
/// The record of the single write, on a run that wrote or would write.
public let record: PatchRecord?
/// What re-attestation did, on a run that wrote.
public let reattestation: DyldSharedCacheReattestation?
public init(
verdict: Verdict,
symbolName: String? = nil,
functionVMA: UInt64? = nil,
gateVMA: UInt64? = nil,
record: PatchRecord? = nil,
reattestation: DyldSharedCacheReattestation? = nil,
) {
self.verdict = verdict
self.symbolName = symbolName
self.functionVMA = functionVMA
self.gateVMA = gateVMA
self.record = record
self.reattestation = reattestation
}
/// Sites this run put on disk — 1 on a live patch, 0 otherwise.
public var sitesWritten: Int {
verdict == .patched ? 1 : 0
}
/// Sites this run found, patched or already patched. This is the number
/// `patch_lockdown_mode` returns: 0 when the symbol is absent, 1
/// otherwise.
public var sitesFound: Int {
verdict == .symbolAbsent ? 0 : 1
}
}
// MARK: - Entry points
/// Patch the cache under `chunksDirectory`.
@discardableResult
public static func patch(
chunksDirectory: URL,
dryRun: Bool = false,
captureUndo: Bool = false,
onUndo: ((DyldSharedCacheUndoLog) -> Void)? = nil,
log: ((String) -> Void)? = DyldSharedCacheCodeSignature.stderrLog,
) throws -> Outcome {
let chunks = try DyldSharedCacheChunkSet(directory: chunksDirectory, captureUndo: captureUndo)
defer {
if captureUndo, let undo = chunks.takeUndoLog() {
onUndo?(undo)
}
}
return try patch(in: chunks, dryRun: dryRun, log: log)
}
/// Patch an already-open cache.
///
/// Writes go through `DyldSharedCacheChunkSet.write(at:_:)`, so the span is recorded
/// and `reattestRecordedWrites` cannot be handed the wrong address. A
/// caller sharing one chunk set across patchers therefore also gets any
/// earlier patcher's pages re-attested here, which is a no-op for pages
/// that are already correct.
@discardableResult
public static func patch(
in chunks: DyldSharedCacheChunkSet,
dryRun: Bool = false,
log: ((String) -> Void)? = DyldSharedCacheCodeSignature.stderrLog,
) throws -> Outcome {
log?(
" [.] \(chunks.directory.path) "
+ "(\(chunks.chunkURLs.count) chunk(s), \(chunks.mappings.count) mapping(s))",
)
guard let block = try resolveBlockInvoke(in: chunks) else {
log?(
" [=] os_lockdown_mode_enabled not present "
+ "(pre-iOS-27 userland); nothing to patch",
)
return Outcome(verdict: .symbolAbsent)
}
log?(" [.] \(block.name) @ 0x\(hex(block.vma))")
let instructions = try disassembleBlock(in: chunks, at: block.vma)
guard let gate = findErrorGate(instructions) else {
throw PatcherError.patchSiteNotFound(
"lockdown_mode: `cmn wR,#1; b.eq <crash>` sysctl-error gate not found "
+ "(nor an already-NOPed one)",
)
}
log?(" [.] gate @ 0x\(hex(gate.address)): \(gate.mnemonic) \(gate.operandString)")
let nop = ARM64.nop
let current = try chunks.bytesAtVMA(gate.address, length: nop.count)
guard current != nop else {
log?(
" [=] already patched at 0x\(hex(gate.address)); "
+ "nothing to patch/re-attest",
)
return Outcome(
verdict: .alreadyPatched,
symbolName: block.name,
functionVMA: block.vma,
gateVMA: gate.address,
)
}
let record = try record(for: gate, original: current, replacement: nop, in: chunks)
log?(
" [+] \(dryRun ? "would write" : "wrote") nop at 0x\(hex(gate.address)) "
+ "(\(current.hex) -> \(nop.hex))",
)
guard !dryRun else {
return Outcome(
verdict: .wouldPatch,
symbolName: block.name,
functionVMA: block.vma,
gateVMA: gate.address,
record: record,
)
}
try chunks.write(at: gate.address, nop)
let reattestation = try DyldSharedCacheCodeSignature.reattestRecordedWrites(in: chunks, log: log)
guard try chunks.bytesAtVMA(gate.address, length: nop.count) == nop else {
throw PatcherError.patchVerificationFailed(
"lockdown_mode: post-write verify failed at 0x\(hex(gate.address))",
)
}
log?(" [+] lockdown-mode crash patch complete")
return Outcome(
verdict: .patched,
symbolName: block.name,
functionVMA: block.vma,
gateVMA: gate.address,
record: record,
reattestation: reattestation,
)
}
// MARK: - Reveal
/// The first of `symbolCandidates` the cache's own `.symbols` table knows.
///
/// A missing symbol is `nil` — the pre-iOS-27 case. A missing or
/// unparseable symbol table throws, because "there is nothing to look in"
/// must not be reported as "this userland does not have the block".
static func resolveBlockInvoke(in chunks: DyldSharedCacheChunkSet) throws -> (name: String, vma: UInt64)? {
for name in symbolCandidates {
if let vma = try chunks.resolveLocalSymbol(name) {
return (name, vma)
}
}
return nil
}
/// Decode the block from `vma` up to its first `ret`/`retab`, or
/// `maxInstructions`, whichever comes first.
///
/// The window is truncated at the end of what is addressable rather than
/// padded with whatever follows in the chunk file, which is where this
/// differs from `_disasm_function` in the reference: a block sitting at the
/// very end of a mapping decodes as far as it really extends here, instead
/// of running on into the next region's bytes. On this cache the block is
/// nowhere near a boundary, so both read the same instructions.
/// Stops at an undecodable word as well. `ARM64Disassembler` sets
/// `cs.skipData = true` and the reference's `_cs` (`cfw_asm.py:14`) does
/// not, so where Capstone cannot decode a word the Python's `cs.disasm`
/// ends the stream and this one hands back a data pseudo-instruction
/// (`id == 0`) and carries on. Left alone that inverts the failure mode on
/// a userland whose block carries an inline literal before the gate: the
/// Python truncates, `findErrorGate` finds nothing and the install stops
/// loudly, while this would decode on past the data into whatever follows
/// the block and — if a `bl` / `cmn wR,#1` / `b.eq` triple happened to
/// appear there — NOP a branch in unrelated code and re-attest that page.
/// A wrong patch that passes its own signature check is worse than a
/// failed install. `DyldSharedCacheLSDEmbeddedRegPatcher.disassembleFunction` breaks on
/// the same condition for the same reason.
static func disassembleBlock(in chunks: DyldSharedCacheChunkSet, at vma: UInt64) throws -> [ARM64Instruction] {
let window = try chunks.readAtVMA(vma, length: maxInstructions * 4, allowShort: true)
var decoded: [ARM64Instruction] = []
for insn in disassembler.disassemble(window, at: vma, count: maxInstructions) {
guard insn.isDecoded else { break }
decoded.append(insn)
if insn.mnemonic == "ret" || insn.mnemonic == "retab" {
break
}
}
return decoded
}
/// The `cmn wR, #1; b.eq` sysctl-error idiom, preceded by a call.
///
/// The branch slot also matches once it holds the NOP this patch writes.
/// Without that, a second pass over an already-installed cache never
/// reaches the byte comparison in `patch(in:dryRun:log:)` — the idiom it
/// searches for is the one the patch has already replaced — and the run
/// fails instead of reporting a no-op. The `bl` + `cmn wR, #1` anchor is
/// unchanged, so widening the slot does not weaken where a match can land,
/// and re-writing a NOP over a NOP is inert.
static func findErrorGate(_ instructions: [ARM64Instruction]) -> ARM64Instruction? {
guard instructions.count >= 2 else { return nil }
var sawCall = false
for index in 0 ..< (instructions.count - 1) {
let insn = instructions[index]
if insn.mnemonic == "bl" {
sawCall = true
}
guard sawCall else { continue }
guard insn.mnemonic == "cmn", immediate(of: insn, at: 1) == 1 else { continue }
let gate = instructions[index + 1]
if gate.mnemonic == "b.eq" || gate.mnemonic == "nop" {
return gate
}
}
return nil
}
/// The instruction's operand at `index`, when that operand is an immediate.
///
/// Semantic, not textual: the `#1` of `cmn w0, #1` is read off the decode,
/// so a build that prints it as `#0x1` matches just the same.
static func immediate(of insn: ARM64Instruction, at index: Int) -> Int64? {
guard let operands = insn.detail?.operands,
index < operands.count,
operands[index].type == .immediate
else { return nil }
return operands[index].imm
}
// MARK: - Reporting
private static func record(
for gate: ARM64Instruction,
original: Data,
replacement: Data,
in chunks: DyldSharedCacheChunkSet,
) throws -> PatchRecord {
let span = DyldSharedCacheWriteSpan(vma: gate.address, length: replacement.count)
let (chunkURL, range) = try chunks.fileRange(of: span)
return PatchRecord(
patchID: "dyld-boot-lockdown_mode",
component: chunkURL.lastPathComponent,
fileOffset: range.lowerBound,
virtualAddress: gate.address,
originalBytes: original,
patchedBytes: replacement,
beforeDisasm: "\(gate.mnemonic) \(gate.operandString)",
afterDisasm: "nop",
description: "NOP `\(gate.mnemonic) \(gate.operandString)` so a missing "
+ "security.mac.lockdown_mode_state_public sysctl reads 0 instead of aborting",
)
}
private static func hex(_ value: UInt64) -> String {
String(value, radix: 16, uppercase: true)
}
}