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

> Understand how entitlements are applied during CFW installation. Explore the differences between ldid-procursus and the host driver in the vphone-cli repository.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: deep-dive
- Published: 2026-09-08

---

**Entitlements are applied exclusively inside the [`cfw_install.sh`](https://github.com/Lakr233/vphone-cli/blob/main/cfw_install.sh) installer using `ldid-procursus` to re-sign patched binaries, while the host-side [`cfw_install_host.sh`](https://github.com/Lakr233/vphone-cli/blob/main/cfw_install_host.sh) driver only mounts the VM image and delegates signing operations without handling entitlements itself.**

The [vphone-cli](https://github.com/Lakr233/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`](https://github.com/Lakr233/vphone-cli/blob/main/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.

```bash

# 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`.

```bash

# 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.

```bash
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`](https://github.com/Lakr233/vphone-cli/blob/main/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.

```bash

# 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`](https://github.com/Lakr233/vphone-cli/blob/main/cfw_install.sh) or its variants.

## Tooling and Dependencies

The repository declares `ldid-procursus` as a mandatory dependency in [`scripts/setup_tools.sh`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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`](https://github.com/Lakr233/vphone-cli/blob/main/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.