カーネルログからの出力：example/open1_hook.cをコンパイルして実行した後
xnuspyは、新しいシステムコールxnuspy_ctlをインストールするpongoOSモジュールであり、ユーザー空間からカーネル関数をフックすることができます。iOS 13.x、iOS 14.x、iOS 15.xを、checkra1n 0.12.2以降でサポートしています。4Kデバイスはサポートされていません。
このモジュールはKTRR/KPPを完全に無効化し、EL1内でRWXメモリを作成することを可能にします。メイン端末では使用しないでください。
libusbが必要：brew install libusb
トップレベルディレクトリでmakeを実行します。ローダーとモジュールがビルドされます。
makeの前にこれらを追加します。
XNUSPY_DEBUG=1
kprintf）に送信します。XNUSPY_SERIAL=1
IOLogに送信します。XNUSPY_LEAKED_PAGE_LIMIT=n
64です。詳細はカーネルパニックのデバッグを参照してください。XNUSPY_TRAMP_PAGES=n
XNUSPY_DEBUGとXNUSPY_SERIALは互いに依存しません。
すべてをビルドした後、checkra1nでデバイスをpongoシェルで起動します：/Applications/checkra1n.app/Contents/MacOS/checkra1n -p
ローダーとモジュールをビルドしたのと同じディレクトリで、loader/loader module/xnuspyを実行します。その後、xnuspyが処理を行い、数秒でデバイスが起動します。loaderはxnuspy-getkernelvを発行した後、SEPROMのエクスプロイトが必要な場合に備えてさらに数秒待機します。
たまに、私のいくつかの端末では、checkra1nのKPFが実行された後で"起動中"で停止することがあります。原因はまだわかっていませんが、発生した場合は再試行してください。また、bootx後にデバイスがハングした場合も再試行してください。最後に、iOS 13.3.1を搭載したiPhone Xでコンパイルされたxnuspy_ctlコードを実行可能としてマークするのはやや不安定ですが、他の端末では100%成功します。フックプログラムを実行するときにカーネル命令フェッチアボートでパニックになった場合は、再試行してください。
xnuspyはenosysシステムコールをパッチして、xnuspy_ctl_trampを指すようにします。これは小さなトランポリンで、コンパイルされたxnuspy_ctlコードを実行可能としてマークし、そこに分岐します。xnuspy_ctlの実装はmodule/el1/xnuspy_ctl/xnuspy_ctl.cにあり、例はexampleディレクトリにあります。
include/xnuspy/内にはxnuspy_ctl.hがあり、xnuspy_ctlの定数を定義するヘッダーです。これはカーネル関数をフックするすべてのプログラムにインクルードされることを意図しています。
sysctlbynameを使用して、どのシステムコールがパッチされたかを確認できます：```
size_t oldlen = sizeof(long);
long SYS_xnuspy_ctl = 0;
sysctlbyname("kern.xnuspy_ctl_callnum", &SYS_xnuspy_ctl, &oldlen, NULL, 0);
このシステムコールは4つの引数`flavor`、`arg1`、`arg2`、`arg3`を取ります。
フレーバーは`XNUSPY_CHECK_IF_PATCHED`、`XNUSPY_INSTALL_HOOK`、
`XNUSPY_REGISTER_DEATH_CALLBACK`、`XNUSPY_CALL_HOOKME`、`XNUSPY_CACHE_READ`、
`XNUSPY_KREAD`、`XNUSPY_KWRITE`、または`XNUSPY_GET_CURRENT_THREAD`のいずれかです。
残りの3つの引数の意味はフレーバーに依存します。
## `XNUSPY_CHECK_IF_PATCHED`
これは`xnuspy_ctl`が存在するか確認するためのものです。このフレーバーで呼び出すと`999`が返されます。他の引数の値は無視されます。
## `XNUSPY_INSTALL_HOOK`
このフレーバーは[`MSHookFunction`](http://www.cydiasubstrate.com/api/c/MSHookFunction/)のAPIに合わせて設計しました。
`arg1`はフックしたいカーネル関数の*スライドされていない*アドレスです。スライドされたアドレスを指定すると、ほぼ確実にパニックが発生します。`arg2`はABI互換の置換関数へのポインタです。`arg3`は、`xnuspy_ctl`が元のカーネル関数を表すトランポリンのアドレスを`copyout`するためのポインタです。元の関数を呼び出すつもりがない場合は`NULL`にできます。
## `XNUSPY_REGISTER_DEATH_CALLBACK`
このフレーバーでは、オプションの「デスコールバック」、つまりフックプログラムが終了したときにxnuspyが呼び出す関数を登録できます。カーネルフックで作成したものをクリーンアップする機会を提供します。カーネルスレッドを作成した場合は、この関数で終了するように指示します。
コールバックは非同期で呼び出されるわけではないため、ブロックするとxnuspyのガベージコレクションスレッドの実行が妨げられます。
`arg1`はコールバック関数へのポインタです。他の引数の値は無視されます。
## `XNUSPY_CALL_HOOKME`
`hookme`は、xnuspyがxnuspyキャッシュを通じてエクスポートする小さなアセンブリスタブで、フックするためのものです。このフレーバーで`xnuspy_ctl`を呼び出すと`hookme`が呼び出され、実際のカーネル関数をフックしなくても簡単にカーネルコード実行を獲得する方法を提供します。
`arg1`は`hookme`が呼び出されたときに渡される引数です。`NULL`にできます。
## `XNUSPY_CACHE_READ`
このフレーバーでは、xnuspyキャッシュから読み取る方法を提供します。キャッシュには`kprintf`、`current_proc`、`kernel_thread_start`、いくつかのlibc関数、カーネルスライドなど、多くの便利なものが含まれているため、自分で見つける必要はありません。キャッシュIDの完全なリストについては、`example/xnuspy_ctl.h`を参照してください。
`arg1`は`xnuspy_ctl.h`で定義されたキャッシュIDの1つで、`arg2`は`xnuspy_ctl`が要求したアドレスまたは値を`copyout`するためのポインタです。他の引数の値は無視されます。
## `XNUSPY_KREAD`
このフレーバーでは、tfp0を使わずにユーザースペースからカーネルメモリを簡単に読み取る方法を提供します。
`arg1`はカーネル仮想アドレス、`arg2`はユーザースペースバッファのアドレス、`arg3`はそのユーザースペースバッファのサイズです。`arg1`から`arg2`へ`arg3`バイトが書き込まれます。
## `XNUSPY_KWRITE`
このフレーバーでは、tfp0を使わずにユーザースペースからカーネルメモリに簡単に書き込む方法を提供します。
`arg1`はカーネル仮想アドレス、`arg2`はユーザースペースバッファのアドレス、`arg3`はそのユーザースペースバッファのサイズです。`arg2`から`arg1`へ`arg3`バイトが書き込まれます。
## `XNUSPY_GET_CURRENT_THREAD`
このフレーバーは、呼び出し元スレッドのカーネルアドレスをユーザースペースに提供します。
`arg1`は`xnuspy_ctl`が`current_thread`の戻り値を`copyout`するためのポインタです。他の引数の値は無視されます。
### エラー
`XNUSPY_CHECK_IF_PATCHED`を除くすべてのフレーバーでは、成功時に`0`が返されます。エラー時には`-1`が返され、`errno`が設定されます。`XNUSPY_CHECK_IF_PATCHED`はエラーを返しません。XNUの`mach_to_bsd_errno`を使用して`kern_return_t`を適切な`errno`に変換します。
#### `XNUSPY_INSTALL_HOOK`に関するエラー
`errno`は次のように設定されます...
- `EEXIST`の場合:
- `arg1`で示されるスライドされていないカーネル関数に既にフックが存在する。
- `ENOMEM`の場合:
- `unified_kalloc`が`NULL`を返した。
- `ENOSPC`の場合:
- 空き`xnuspy_tramp`構造体がない。これはxnuspy内部のデータ構造です。同時に何百ものカーネル関数をフックしているのでなければ発生しません。より多くの関数フックが必要な場合は、[制限](#limits)を参照してください。
- `ENOTSUP`の場合:
- 呼び出し元がMach-O実行可能ファイルまたは動的ライブラリからのものでない。
- `ENOENT`の場合:
- `mh_for_addr`が、呼び出し元のアドレス空間内で`arg2`に対応するMach-Oヘッダを特定できなかった。
- `EFAULT`の場合:
- 特定されたMach-Oヘッダが実際にはMach-Oヘッダではない。これはおそらく発生しません。
- `EIO`の場合:
- `mach_make_memory_entry_64`が、特定されたMach-Oヘッダの`__TEXT`セグメントと`__DATA`セグメント全体に対するメモリエントリを返さなかった。
`errno`は、`vm_map_wire_external`、`mach_vm_map_external`、`mach_make_memory_entry_64`、`copyin`、`copyout`、および該当する場合は1回限りの初期化関数の戻り値にも依存します。
このフレーバーがエラーを返した場合、対象のカーネル関数はフックされませんでした。`arg3`に非`NULL`ポインタを渡した場合、そのポインタは初期化されている場合とされていない場合があります。初期化されていない場合は使用すると危険です。
#### `XNUSPY_REGISTER_DEATH_CALLBACK`に関するエラー
`errno`は次のように設定されます...
- `ENOENT`の場合:
- 呼び出し元のプロセスがカーネル関数を1つもフックしていない。
このフレーバーがエラーを返した場合、デスコールバックは登録されませんでした。
#### `XNUSPY_CALL_HOOKME`に関するエラー
`errno`は次のように設定されます...
- `ENOTSUP`の場合:
- `hookme`が`xnuspy_tramp`構造体を含むメモリから遠すぎる。これはpongoOS内で判断され、xnuspyがカーネルキャッシュ内の未使用コードにフォールバックしなければならなかった場合にのみ発生します。この場合、`hookme`を呼び出すとほぼ確実にカーネルパニックが発生するため、別のカーネル関数をフックする方法を見つける必要があります。
このフレーバーがエラーを返した場合、`hookme`は呼び出されませんでした。
#### `XNUSPY_CACHE_READ`に関するエラー
`errno`は次のように設定されます...
- `EINVAL`の場合:
- `arg1`で示される定数がキャッシュ内の何も表していない。
- `arg1`が`IO_LOCK`だが、カーネルがiOS 14.4.2以下またはiOS 15.xである。
- `arg1`が`IPC_OBJECT_LOCK`だが、カーネルがiOS 15.xである。
- `arg1`が`IPC_PORT_RELEASE_SEND`だが、カーネルがiOS 14.5以上である。
- `arg1`が`IPC_PORT_RELEASE_SEND_AND_UNLOCK`だが、カーネルがiOS 14.4.2以下である。
- `arg1`が`KALLOC_CANBLOCK`だが、カーネルがiOS 14.x以上である。
- `arg1`が`KALLOC_EXTERNAL`だが、カーネルがiOS 13.xである。
- `arg1`が`KFREE_ADDR`だが、カーネルがiOS 14.x以上である。
- `arg1`が`KFREE_EXT`だが、カーネルがiOS 13.xである。
- `arg1`が`PROC_REF`だが、カーネルがiOS 14.8以下である。
- `arg1`が`PROC_REF_LOCKED`だが、カーネルがiOS 15.xである。
- `arg1`が`PROC_RELE`だが、カーネルがiOS 14.8以下である。
- `arg1`が`PROC_RELE_LOCKED`だが、カーネルがiOS 15.xである。
- `arg1`が`VM_MAP_UNWIRE`だが、カーネルがiOS 15.xである。
- `arg1`が`VM_MAP_UNWIRE_NESTED`だが、カーネルがiOS 14.8以下である。
`errno`は、`copyout`の戻り値、および該当する場合は1回限りの初期化関数の戻り値にも依存します。
このフレーバーがエラーを返した場合、`arg2`に渡したポインタは初期化されませんでした。
#### `XNUSPY_KREAD`および`XNUSPY_KWRITE`に関するエラー
`errno`は次のように設定されます...
- `EFAULT`の場合:
- `arg1`または`arg2`のアドレス変換に失敗した。`XNUSPY_DEBUG=1`でコンパイルした場合、そのメッセージがカーネルログに出力されます。
このフレーバーがエラーを返した場合、カーネルメモリは読み取り/書き込みされませんでした。
#### `XNUSPY_GET_CURRENT_THREAD`に関するエラー
`copyout`が失敗した場合、`errno`はその戻り値に設定されます。
# 重要な情報
### よくある落とし穴
置換関数を書いているとき、自分がカーネルコードを書いていることを忘れがちでした。フックを書く際に留意すべき点をいくつか挙げます：
- *プログラムの`__TEXT`セグメントの外にあるユーザースペースコードは実行できません*。たとえば、うっかり`kprintf`の代わりに`printf`を呼び出すとパニックになります。呼び出したいlibc関数が`XNUSPY_CACHE_READ`で既に利用可能でない場合は、その関数を再実装する必要があります。ただし、他のカーネル関数への関数ポインタを作成してそれらを呼び出すことはできます。
- *ユーザースペースコードでよく使われる多くのマクロはカーネルでは安全ではありません*。たとえば、`PAGE_SIZE`は定数ではなく`vm_page_size`に展開されます。この変数を読み取る前にPANを無効にする（A10+では推奨しません）必要があります。そうしないとパニックになります。
- *コードを`-fno-stack-protector`および`-D_FORTIFY_SOURCE=0`でコンパイルしてください*。場合によっては、デバイスが別のユーザースペースポインタを逆参照して`___stack_chk_guard`を読み取る必要があり、A10+ではパニックになります。
- *安全のため、フックプログラムをコンパイラ最適化なしでコンパイルしてください*。
https://developer.apple.com/library/archive/documentation/Darwin/Conceptual/KernelProgramming/style/style.html にざっと目を通すこともお勧めします。
### カーネルパニックのデバッグ
コードを書くときにはバグは避けられないため、最終的にはカーネルパニックを引き起こすことになります。パニックは必ずしもxnuspyのバグを意味するわけではないため、問題を報告する前に、元の関数を呼び出してその値を返す以外何もしない場合でもパニックが発生することを確認してください。それでもパニックが発生する場合は、おそらくxnuspyのバグです（その場合は問題を報告してください）。しかし、パニックが発生しない場合は、置換関数に問題があります。