Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Documents/en/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ New to vphone? Read [Overview](get-started/overview.md), then follow [Quick Star
| [Automation API](machines/automation-api.md) | The optional local HTTP and WebSocket interface |
| [Device Name and Clock](machines/device-name-and-clock.md) | What the guest takes from the VM name and the Mac's clock |
| [Package Environment](machines/package-environment.md) | Installing and removing a package manager in the guest |
| [Cryptexes](machines/cryptexes.md) | Installing your own programs in a trusted darwinOS guest as a cryptex |

## Firmware and Devices

Expand Down
2 changes: 1 addition & 1 deletion Documents/en/launchpad/launchpad-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ The result names the template, whether this creation built it, and the patches i

Two more cases run steps as root through the helper:

- `--preset minimal` (Minimal: a stock boot chain, kernel and TXM, with the system customized before the restore) is also restored on its own without slimming, and its `fw patch` runs as root through the helper. Its Userspace debugging box (`userspace-debugging` under Features in `vphone-cli fw patches`) is an `--allow` for each patch it lists.
- `--preset minimal` (Minimal: a stock boot chain, kernel and TXM, with the system customized before the restore) is also restored on its own without slimming, and its `fw patch` runs as root through the helper. Its Userspace debugging box (`userspace-debugging` under Features in `vphone-cli fw patches`) is an `--allow` for each patch it lists. Its Trusted darwinOS environment box (`trusted-darwinos`, which is `--allow filesystem-exp-trusted_darwinos`) restores an iPhone or iPad as trusted darwinOS with cloudOS's cryptexctl, so a cryptex can be installed while it runs (Apps › Install Cryptex… in the VM window; see [Cryptexes](../machines/cryptexes.md)), and the box's summary says what it changes. The guest then enforces Restricted Execution Mode, and a research-board guest (cloudOS 26.5 to 26.7) cannot turn on Developer Mode, and changing the box takes effect only with a new restore.
- For a machine whose cloudOS has no vphone600 components (its release's own cloudOS, a watch, an iOS 18 guest), the kernelcache mix is staged with `fw kernelcache` and linked by the helper as root.

### Patch overrides
Expand Down
45 changes: 45 additions & 0 deletions Documents/en/machines/cryptexes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# Cryptexes

A cryptex is a signed disk image that the guest mounts while it runs, with a trust cache for the programs in it. Use one to run your own programs in a `minimal` guest without restoring it again.

## Before you start

- Create the machine with the `minimal` preset and the **Trusted darwinOS environment** box on, on New Machine's Patches page. With `vphone-launchpad-cli`, that is `--preset minimal --allow filesystem-exp-trusted_darwinos`. The box takes effect only with a restore: turning it on for an existing machine means creating it again.
- Use an iOS 26 or iOS 18 IPSW. iOS 26.5 with cloudOS 26.5 and iOS 18.6 with cloudOS 18.6 work. iOS 27 does not boot in this environment, so vphone-cli refuses the box with an iOS 27 IPSW before it restores anything.
- Install the macOS Security Research tools (the PCC Virtual Research Environment). The VM window builds cryptexes with their `/System/Library/SecurityResearch/usr/bin/cryptexctl.research`.
- The guest needs network. Installing a cryptex asks Apple's signing server to personalize it for this guest.

In this environment the guest enforces Restricted Execution Mode, and a guest on a research-board cloudOS (26.5 to 26.7) cannot turn on Developer Mode.

## Install a cryptex

1. Put the files the cryptex holds in a folder, laid out as they appear in the cryptex. For example:

```
mycryptex/
usr/bin/server
Library/LaunchDaemons/server.plist
```

Sign each program ad hoc with the entitlements it needs (`codesign -s - --entitlements entitlements.plist usr/bin/server`).
2. In the VM window, choose **Apps › Install Cryptex…** and select that folder.

The VM window builds the cryptex for this guest, uploads it, and the guest personalizes and installs it. The folder's name, without its extension, becomes the cryptex's identifier. It is mounted at `/private/var/DarwinDataCenterSupportImage/<identifier>`, so for the folder `mycryptex` above, `usr/bin/server` is `/private/var/DarwinDataCenterSupportImage/mycryptex/usr/bin/server` in the guest. The alert after the install names the path. Launch daemons in the cryptex's `Library/LaunchDaemons` are started from it.

**Apps › List Cryptexes** shows what is installed, with each cryptex's mount point.

A cryptex installed from the VM window stays until the guest restarts; install it again after a restart. To keep one across restarts, install it from a script with `persist` (see below).

Several cryptexes can be installed at once, each at its own path. A folder whose name is already installed as a cryptex is refused: uninstall that cryptex first with `cryptex.uninstall` (see below), or rename the folder.

## Choose the folder, not a `.cxbd`

Install Cryptex… also takes a `.cxbd` and installs it as it is, but only one made for this guest: a Cryptex1 cryptex for the vresearch101 board, as `cryptexctl.research create` makes it with `--BORD=0x90 --CHIP=0xfe01`. Choose the folder in every other case.

A cryptex built for a Security Research Device iPhone does not install. `cryptexctl create --research`, which the SRD examples and their Makefiles use, makes that kind. Install Cryptex… names it and stops before uploading. Choose the folder it was built from instead; with a Makefile, that is often `build/<identifier>.root`, the folder whose contents went into the disk image.

## From a script

vphoned offers `cryptex.list`, `cryptex.install` and `cryptex.uninstall` through the [Automation API](automation-api.md). `cryptex.install` takes a `.cxbd` already uploaded under `/var/mobile/Documents/vphone-cryptexes` and the variant it was created with. With `persist: true`, vphoned installs the cryptex again each time the guest restarts, which needs network if the guest has to ask Apple's signing server again; `cryptex.list` names these cryptexes under `persisted`, and `cryptex.uninstall` removes one for good.

For the implementation, see [`Research/Firmware/trusted_darwinos_cryptexes.md`](../../../Research/Firmware/trusted_darwinos_cryptexes.md).
1 change: 1 addition & 0 deletions Documents/ja/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ vphone を初めて使う場合は、[概要](get-started/overview.md)を読ん
| [自動化 API](machines/automation-api.md) | 任意で有効にできるローカルの HTTP と WebSocket インターフェース |
| [デバイス名と時計](machines/device-name-and-clock.md) | ゲストが仮想マシン名と Mac の時計から受け取るもの |
| [パッケージ環境](machines/package-environment.md) | ゲストへのパッケージマネージャのインストールと削除 |
| [Cryptex](machines/cryptexes.md) | trusted darwinOS ゲストへの独自プログラムの cryptex としてのインストール |

## ファームウェアとデバイス

Expand Down
2 changes: 1 addition & 1 deletion Documents/ja/launchpad/launchpad-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ vphone-launchpad-cli vm create rt-e --block system-debugserver-cfw-install

さらに 2 つの場合では、ヘルパーを通じて root として手順が実行されます。

- `--preset minimal`(Minimal:未変更のブートチェーン、カーネル、TXM を使い、復元前にシステムをカスタマイズします)も軽量化なしで単独で復元され、その `fw patch` はヘルパーを通じて root として実行されます。Userspace debugging のボックス(`vphone-cli fw patches` の Features にある `userspace-debugging`)は、そこに記載された各パッチに対する `--allow` です。
- `--preset minimal`(Minimal:未変更のブートチェーン、カーネル、TXM を使い、復元前にシステムをカスタマイズします)も軽量化なしで単独で復元され、その `fw patch` はヘルパーを通じて root として実行されます。Userspace debugging のボックス(`vphone-cli fw patches` の Features にある `userspace-debugging`)は、そこに記載された各パッチに対する `--allow` です。Trusted darwinOS environment のボックス(`trusted-darwinos`、つまり `--allow filesystem-exp-trusted_darwinos`)は、iPhone または iPad を trusted darwinOS として復元し、cloudOS の cryptexctl を追加します。これにより、ゲストの実行中に cryptex をインストールできます(VM ウインドウの Apps › Install Cryptex…。[Cryptex](../machines/cryptexes.md) を参照)。ボックスの説明に、その影響が記載されています。ゲストでは Restricted Execution Mode が強制され、リサーチボードのゲスト(cloudOS 26.5〜26.7)ではデベロッパモードをオンにできません。ボックスの変更は、復元をやり直したときにのみ反映されます。
- cloudOS に vphone600 のコンポーネントがないマシン(そのリリース自身の cloudOS、Watch、iOS 18 ゲスト)では、kernelcache ミックスを `fw kernelcache` で準備し、ヘルパーが root としてリンクします。

### パッチの上書き設定
Expand Down
45 changes: 45 additions & 0 deletions Documents/ja/machines/cryptexes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# Cryptex

Cryptex は、ゲストが実行中にマウントする署名済みディスクイメージで、中のプログラム用のトラストキャッシュを伴います。`minimal` ゲストを再度復元することなく、独自のプログラムを実行するために使います。

## 始める前に

- `minimal` プリセットでマシンを作成し、新規マシンの「パッチ」ページで **Trusted darwinOS environment** のボックスをオンにします。`vphone-launchpad-cli` では `--preset minimal --allow filesystem-exp-trusted_darwinos` です。このボックスは復元時にのみ有効になります。既存のマシンでオンにするには、マシンを作成し直す必要があります。
- iOS 26 または iOS 18 の IPSW を使ってください。iOS 26.5 と cloudOS 26.5、iOS 18.6 と cloudOS 18.6 の組み合わせで動作します。iOS 27 はこの環境では起動しないため、IPSW が iOS 27 のとき、vphone-cli は復元を始める前にこのオプションを拒否します。
- macOS Security Research ツール(PCC Virtual Research Environment)をインストールします。VM ウインドウは、その `/System/Library/SecurityResearch/usr/bin/cryptexctl.research` で cryptex をビルドします。
- ゲストにはネットワークが必要です。cryptex をインストールするときに、Apple の署名サーバにこのゲスト用のパーソナライズを依頼します。

この環境では、ゲストは Restricted Execution Mode を適用し、研究ボード用 cloudOS(26.5〜26.7)上のゲストはデベロッパモードをオンにできません。

## cryptex をインストールする

1. cryptex に含めるファイルを、cryptex 内での配置どおりにフォルダに入れます。例:

```
mycryptex/
usr/bin/server
Library/LaunchDaemons/server.plist
```

各プログラムに、必要なエンタイトルメントを付けてアドホック署名します(`codesign -s - --entitlements entitlements.plist usr/bin/server`)。
2. VM ウインドウで **Apps › Install Cryptex…** を選択し、そのフォルダを選びます。

VM ウインドウがこのゲスト用に cryptex をビルドしてアップロードし、ゲストがそれをパーソナライズしてインストールします。フォルダ名(拡張子を除く)が cryptex の識別子になります。cryptex は `/private/var/DarwinDataCenterSupportImage/<identifier>` にマウントされます。上の例のフォルダ `mycryptex` なら、`usr/bin/server` はゲスト内では `/private/var/DarwinDataCenterSupportImage/mycryptex/usr/bin/server` です。インストール後のアラートにそのパスが表示されます。cryptex の `Library/LaunchDaemons` にある起動デーモンは、cryptex から起動されます。

**Apps › List Cryptexes** で、インストール済みの cryptex とそれぞれのマウントポイントを確認できます。

VM ウインドウからインストールした cryptex は、ゲストを再起動するまで残ります。再起動後はもう一度インストールしてください。再起動後も残すには、スクリプトから `persist` を指定してインストールします(下記参照)。

複数の cryptex を同時にインストールでき、それぞれに専用のパスが割り当てられます。フォルダ名がすでに cryptex としてインストールされている場合は拒否されます。まずその cryptex を `cryptex.uninstall` でアンインストールするか(後述)、フォルダ名を変更してください。

## `.cxbd` ではなくフォルダを選ぶ

Install Cryptex… は `.cxbd` もそのままインストールしますが、このゲスト用に作成されたものに限ります。つまり、`cryptexctl.research create` が `--BORD=0x90 --CHIP=0xfe01` で作成する、vresearch101 ボード用の Cryptex1 cryptex です。それ以外の場合はフォルダを選んでください。

Security Research Device の iPhone 用にビルドされた cryptex はインストールできません。SRD のサンプルやその Makefile が使う `cryptexctl create --research` は、この種類を作成します。Install Cryptex… はそのことを示し、アップロードの前に中止します。代わりに、それをビルドしたフォルダを選んでください。Makefile の場合は、多くは `build/<identifier>.root`、つまり内容がディスクイメージに入れられたフォルダです。

## スクリプトから

vphoned は [自動化 API](automation-api.md) で `cryptex.list`、`cryptex.install`、`cryptex.uninstall` を提供します。`cryptex.install` は、`/var/mobile/Documents/vphone-cryptexes` の下にアップロード済みの `.cxbd` と、その作成時の variant を受け取ります。`persist: true` を指定すると、vphoned はゲストが再起動するたびにその cryptex をもう一度インストールします。Apple の署名サーバーに改めて問い合わせる必要がある場合は、ゲストにネットワークが必要です。`cryptex.list` はこれらの cryptex を `persisted` に示し、`cryptex.uninstall` で完全に取り除けます。

実装については [`Research/Firmware/trusted_darwinos_cryptexes.md`](../../../Research/Firmware/trusted_darwinos_cryptexes.md) を参照してください。
1 change: 1 addition & 0 deletions Documents/ko/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ vphone이 처음이라면 [개요](get-started/overview.md)를 읽은 뒤 [빠
| [자동화 API](machines/automation-api.md) | 선택적으로 사용하는 로컬 HTTP 및 WebSocket 인터페이스 |
| [기기 이름과 시계](machines/device-name-and-clock.md) | 게스트가 가상 머신 이름과 Mac의 시계에서 가져오는 것 |
| [패키지 환경](machines/package-environment.md) | 게스트에 패키지 관리자 설치 및 제거 |
| [Cryptex](machines/cryptexes.md) | trusted darwinOS 게스트에 자신의 프로그램을 cryptex로 설치 |

## 펌웨어와 기기

Expand Down
2 changes: 1 addition & 1 deletion Documents/ko/launchpad/launchpad-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ vphone-launchpad-cli vm create rt-e --block system-debugserver-cfw-install

다음 두 경우에는 도우미를 통해 일부 단계를 root로 실행합니다.

- `--preset minimal`(Minimal: 순정 부트 체인, 커널, TXM을 사용하고 복원 전에 시스템을 사용자화)도 경량화 없이 단독으로 복원되며, `fw patch`는 도우미를 통해 root로 실행됩니다. Userspace debugging 상자(`vphone-cli fw patches`의 Features 아래 `userspace-debugging`)는 그 상자가 나열하는 각 패치에 대한 `--allow`에 해당합니다.
- `--preset minimal`(Minimal: 순정 부트 체인, 커널, TXM을 사용하고 복원 전에 시스템을 사용자화)도 경량화 없이 단독으로 복원되며, `fw patch`는 도우미를 통해 root로 실행됩니다. Userspace debugging 상자(`vphone-cli fw patches`의 Features 아래 `userspace-debugging`)는 그 상자가 나열하는 각 패치에 대한 `--allow`에 해당합니다. Trusted darwinOS environment 상자(`trusted-darwinos`, 즉 `--allow filesystem-exp-trusted_darwinos`)는 iPhone 또는 iPad를 trusted darwinOS로 복원하고 cloudOS의 cryptexctl을 추가하므로, 게스트가 실행 중일 때 cryptex를 설치할 수 있습니다(VM 창의 Apps › Install Cryptex…, [Cryptex](../machines/cryptexes.md) 참조). 상자 아래 설명에 그 영향이 적혀 있습니다. 이후 게스트는 Restricted Execution Mode를 강제하고, 리서치 보드 게스트(cloudOS 26.5~26.7)는 개발자 모드를 켤 수 없으며, 상자를 바꾼 내용은 다시 복원해야만 적용됩니다.
- cloudOS에 vphone600 구성 요소가 없는 머신(해당 릴리스 자체의 cloudOS, Watch, iOS 18 게스트)은 `fw kernelcache`로 kernelcache 믹스를 준비하고 도우미가 root로 링크합니다.

### 패치 재정의
Expand Down
Loading
Loading