How Entitlements Are Applied During CFW Installation: ldid-procursus vs. Host Driver

Entitlements are applied exclusively inside the cfw_install.sh installer using ldid-procursus to re-sign patched binaries, while the host-side cfw_install_host.sh driver only mounts the VM image and delegates signing operations without handling entitlements itself.

The vphone-cli repository orchestrates custom firmware (CFW) installation through a two-phase architecture: a host-side driver that prepares the virtual machine environment, and an installer script that performs binary patching and code signing. Understanding how entitlements are applied during CFW installation requires examining the distinct responsibilities of ldid-procursus inside the VM versus the mounting logic in the host driver. The installer uses the Procursus distribution of ldid to inject private entitlements into patched system binaries, whereas the host script remains uninvolved in entitlement manipulation.

Entitlement Signing Inside the Installer (cfw_install.sh)

The scripts/cfw_install.sh script performs the actual entitlement injection after patching binaries like seputil, launchd_cache_loader, mobileactivationd, and vphoned. Because Apple’s original signatures lack the private keys required for virtualized iPhone operation, the installer re-signs every modified binary with custom entitlements.

The ldid_sign and ldid_sign_ent Helper Functions

The installer defines two Bash functions to standardize code signing. The ldid_sign function applies a standard signature with optional bundle identifier injection, while ldid_sign_ent specifically handles entitlement plists.

# Defined in scripts/cfw_install.sh (lines 71-86)

ldid_sign() {
    local file="$1" bundle_id="${2:-}"
    local args=(-S -M "-K$VM_DIR/$CFW_INPUT/signcert.p12")
    [[ -n "$bundle_id" ]] && args+=("-I$bundle_id")
    ldid "${args[@]}" "$file"
}

The ldid_sign_ent variant accepts an entitlements plist path and passes it to ldid via the -S flag, embedding the XML directly into the binary’s code signature. Both functions use the signcert.p12 certificate shipped in the CFW input archive to generate valid signatures.

Preserving Original Entitlements with ldid -e

Certain binaries must retain their original sandbox profiles while gaining additional private entitlements. For these cases, the installer first extracts existing entitlements using ldid -e, modifies or supplements the plist, then re-signs with ldid_sign_ent.

# Example from the DDI auto-mount block (lines 21-22)

ldid -e "$MNT1/usr/libexec/diskimagesiod.bak" > "$TEMP_DIR/diskimagesiod.ent.plist"
ldid_sign_ent "$TEMP_DIR/diskimagesiod" "$TEMP_DIR/diskimagesiod.ent.plist" "com.apple.diskimagesiod"

This extraction step ensures that binaries like diskimagesiod preserve their embedded sandbox definitions while receiving the additional privileges required for virtualization.

Certificate and Bundle ID Injection

Every signing operation references the signcert.p12 private key and injects a specific bundle identifier. For example, the patched seputil binary receives the com.apple.seputil identifier during signing at line 98 of the installer script.

ldid_sign "$TEMP_DIR/seputil" "com.apple.seputil"

The -K flag specifies the PKCS#12 certificate container, while the -I flag sets the bundle ID within the signature’s Info.plist slot.

Host Driver Responsibilities (cfw_install_host.sh)

The scripts/cfw_install_host.sh driver operates exclusively on the host machine with root privileges and performs no entitlement handling. Its sole purpose is to mount the VM’s Disk.img, verify tool availability, and invoke the appropriate installer script.

# From scripts/cfw_install_host.sh (lines 61-84)

# Mounts the image, then delegates:

( cd "$VM_DIR" && env CFW_HOST_CONTAINER="$CONT" _VPHONE_PATH="$P" \
      zsh "$SCRIPT_DIR/$INSTALLER" . )

While the driver checks that ldid exists in the environment (command -v ldid &>/dev/null), it never executes signing commands. All entitlement operations occur inside the mounted environment after the host script hands off execution to cfw_install.sh or its variants.

Tooling and Dependencies

The repository declares ldid-procursus as a mandatory dependency in scripts/setup_tools.sh (line 30), ensuring the Procursus build of ldid is available via Homebrew before installation begins. This specific distribution provides the necessary cryptographic support for iOS code signing on macOS hosts.

Entitlements themselves are defined in repository plist files such as scripts/vphoned/entitlements.plist, which specifies the private entitlements (PV=3, vsock permissions, etc.) injected into the virtualization daemon.

Summary

• Entitlement injection happens exclusively inside cfw_install.sh using ldid-procursus helper functions that wrap the ldid binary with specific certificate and plist arguments.
• ldid_sign and ldid_sign_ent handle standard signing and entitlements-specific signing respectively, both utilizing the signcert.p12 certificate from the CFW archive.
• Original entitlements are preserved using ldid -e extraction before re-signing, ensuring sandbox profiles remain intact for system binaries.
• The host driver (cfw_install_host.sh) does not modify entitlements; it only mounts the VM disk image and executes the installer script with appropriate environment variables.
• ldid-procursus is a prerequisite declared in setup_tools.sh and verified by the host driver before delegation.

Frequently Asked Questions

What tool actually injects entitlements during CFW installation?

The ldid binary from the ldid-procursus Homebrew package performs the actual entitlement injection. The installer script calls this tool through wrapper functions (ldid_sign and ldid_sign_ent) defined in scripts/cfw_install.sh, passing entitlements plists via the -S flag.

Why does the host driver not handle entitlements directly?

The host driver (cfw_install_host.sh) runs on the host macOS system and lacks direct access to the VM’s file system structure in a way that would allow safe binary modification. Instead, it mounts the VM’s Disk.img and delegates all binary patching and signing operations to the installer script running inside the mounted environment, ensuring proper filesystem context and library availability.

How are existing sandbox profiles preserved when adding private entitlements?

The installer extracts the original code signature’s entitlements using ldid -e <binary> > temp.plist, which dumps the embedded XML to a temporary file. It then passes this extracted plist to ldid_sign_ent, which applies it along with the new private entitlements during re-signing, merging virtualization requirements with Apple’s original sandbox definitions.

Where does the signing certificate come from?

The signing certificate (signcert.p12) ships inside the CFW input archive provided to the installer. The ldid_sign and ldid_sign_ent functions reference this certificate using the -K$VM_DIR/$CFW_INPUT/signcert.p12 argument, allowing the patched binaries to carry valid cryptographic signatures recognized by the virtualized iOS kernel.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}