jcbrtl/kryptonite

Kryptonite enables external GPUs on Macs using Thunderbolt 1 and 2 without compromising on Mac security features such as System Integrity Protection, FileVault, and Authenticated-Root.

Unlike PurgeWrangler, which requires these security features disabled and modifies kernel extensions on the root volume, Kryptonite injects patches via EFI and performs them in memory, when the offending kernel extensions load. This project supercedes the PurgeWrangler system.

Features

With Kryptonite, you get the following benefits over PurgeWrangler:

You only have to set up Kryptonite once, and it will continue to work through Apple software updates.
You can use your mac with all security features enabled - excluding T2 chip if used on those Macs.
Because all patches are performed in memory, your system is untouched when booted without the Kryptonite/OpenCore disk.
Automatic patching for all installations of macOS booted via the Kryptonite/OpenCore disk.
Free benefits from OpenCore such as the ability to enable iGPUs and inject DSDT overrides to address error 12 in Bootcamp.

Additional benefits on macOS Big Sur and later:

Boot volume seal is not tampered with - meaning a truly native experience without compromises.
FileVault can now be used without compromise on old macs along with eGFX support.
Smaller delta software updates are supported as system is clean and security features are enabled.

System

Kryptonite leverages OpenCore with a heavily simplified configuration for native Macs to inject kernel/kext patches into macOS during boots. The patches themselves are implemented in a kernel extension named Kryptonite that leverages Lilu which can patch kexts and processes in memory.

You can control Kryptonite's behavior using boot-args specified in the OpenCore config.plist located in the EFI/OC folder on your bootloader disk. The kernel extension supports the following boot arguments:

Boot Arg	Description
`-krydisable`	Disables Kryptonite on boot.
`-krydbg`	Enables debugging for Kryptonite. Must be used alongside `-liludbg`.
`-krybeta`	Enables Kryptonite on beta/untested versions of macOS. Must be used with `-lilubeta`.
`krygpu=`	Provide GPU vendor to patch for. Must be `AMD` or `NVDA`.
`krytbtv=`	Provide Thunderbolt NHI version. Required for macOS ≤ 10.15. Must be `1` or `2`.

All the above arguments should go into the boot-args String in config.plist in the NVRAM section. For example, if you want to set to patch for AMD GPUs, your boot-args would have:

krygpu=AMD

Disclaimer

As with most open source software hacks, you use this software at your own risk. Kryptonite uses OpenCore to inject patches via EFI. Please keep in mind that while these packages are tested extensively, there is always an extremely small chance something could go wrong and brick your device.

Installation

The steps are as follows:

If you are using this on a T2 mac, please disable T2 security.
If you have used PurgeWrangler before, it must be uninstalled:
```
purge-wrangler -u
```
If you want to re-enable SIP and FileVault (ART), please reinstall macOS on top of your existing install before proceeding.
Go to Disk Utility and create a new MS-DOS (FAT32) partition (internal or external) if you do not already have a bootloader disk. If you are using OpenCore already, such as with OpenCore Legacy Patcher to run unsupported macOS versions, you can skip this step. Recommended disk size is 100 MB.

Easy-install via Terminal:

cd ~; curl -qLs https://github.com/mayankk2308/kryptonite/raw/main/Installer/Installer.zip -o Installer.zip; ditto -x -k Installer.zip .; cd Installer; chmod +x installer.sh; ./installer.sh; cd ../; rm -rf Installer*

In the installer, make sure to select the boot disk you created in the previous step or use your existing bootloader disk.

When booting the system, press and hold OPTION key, then select the Kryptonite/OpenCore boot disk.
This will launch another boot menu where you can select your macOS boot drive. Booting from here will patch the system in memory.

Manual Installs

You can directly download the Kryptonite OpenCore configurations from the Releases section and place the extracted EFI folder onto a MS-DOS (FAT32) volume. If you already have a configuration to work with, all you really need to do is move Kryptonite.kext (and Lilu if you don't already have it) to your bootloader's Kext folder, and update config.plist with the kext details in the Kernel > Add section. Finally, you need to supply the correct boot arguments to Kryptonite, which you can find here.

Post-Install

Once configured, you will most likely not require any changes with respect to eGPU support. If there is a newer release of the Kryptonite packages and you want to get them, simply start the installation process above and and recreate/update your bootloader. Some further notes:

The kernel extensions are automatically disabled on untested/beta versions of macOS. To enable them, follow these instructions.
If you want to boot directly into macOS without requiring to select the boot disk on every startup, follow these steps.
If you tried using the DEBUG versions of the kexts and you have a much older slower mac, it may be possible that the system is not patched in time and may not work as expected. In that case, it is good to try the RELEASE version which should be faster.

Uninstallation

Uninstalling Kryptonite is very straightforward:

On boot, press and hold OPTION key.
Select your macOS boot volume instead of Kryptonite.
Press CTRL + ENTER to set it as default boot volume and boot normally.
Delete the Kryptonite partition/disk via Disk Utility.
Reset NVRAM only if SIP is currently enabled for your system. Otherwise, delete boot-args as follows:
```
sudo nvram -d boot-args
```

At step 4, you can alternatively keep the disk and use it on-demand by selecting it manually during boot. If you want to use OpenCore but remove Kryptonite, you can simply disable the kernel extension in your config.plist.

Debugging

If you have issues, please share your logs. To do this, first ensure you create the bootloader again and use DEBUG resources using the installer. If you have a pre-configured OpenCore setup (such as with OpenCore Legacy Patcher), then enable debug mode as follows: https://dortania.github.io/OpenCore-Install-Guide/troubleshooting/debug.html

Additionally, make sure to add the following boot-args for kext debugging:

-liludbgall -krydbg liludump=60

You can add the boot-args to the OpenCore config.plist boot-args section alongside your other arguments. When you boot the debug configuration for OpenCore, you will find the logs generated next to the EFI folder on your bootloader disk. For the kext logs from Lilu, check /var/log/ folder for logs. For debugging, we would need both these files.

Configuration

To manually edit configurations, use ProperTree to open the config.plist file on your bootloader. This file is located on your bootloader disk in the EFI/OC/ directory. If you are comfortable doing so, you can edit the file in TextEdit - just be careful with the format and XML tags. This section describes some common configuration changes you may want to make:

Automatically Booting macOS via Kryptonite

By default, when booting via Kryptonite, you will get a boot picker that times out after 5 seconds. However, if you only have a single macOS installation and always want to boot directly into it without having to see the bootloader or wait for timeout:

In your config.plist, set Timeout in the Misc > Boot section to 0.
Also set ShowPicker in Misc > Boot section to False (or 0).
When booting, press and hold OPTION key to bring up the default Apple bootpicker.
Navigate to the Kryptonite boot disk and press CTRL + ENTER to make it the default boot volume from now on.

Your system should now boot via Kryptonite every time and not show the bootloader.

Disabling NVIDIA Discrete GPU

If you are using an AMD eGPU with a Mac that has a discrete NVIDIA GPU, display outputs may not work on the eGPU. To fix this, you can disable the discrete GPU. This is only applicable for macs with dual GPUs, such as MacBook Pros:

Configure the bootloader to power off the NVIDIA GPU. Follow instructions here. Use the DeviceProperties approach on that page.
Switch mux to iGPU:

sudo nvram FA4CE28D-B62F-4C99-9CC3-6815686E30F9:gpu-power-prefs=%01%00%00%00

Sometimes this may not work. A good indicator that it worked is that when you boot, the boot chime is heard but there is a small delay before the display backlight comes on. If it does not work, there is no other option but to retry. You can switch mux back to normal as follows:

sudo nvram FA4CE28D-B62F-4C99-9CC3-6815686E30F9:gpu-power-prefs=%00%00%00%00

License

This project is licensed under GPL-3.0, while its underlying dependencies such as OpenCore and Lilu are licensed under BSD-3-Clause license.

Credits

Software and Frameworks

Apple for macOS.
acidanthera and it's contributors for OpenCore.
acidanthera and it's contributors for Lilu.

Patches

@mayankk2308/@mac_editor for:
- Thunderbolt patches for native eGFX support on macOS 10.13.4-10.15.1.
- Updated Thunderbolt patches for native eGFX support on macOS 10.15.1+.
- Bypass for Thunderbolt driver compatibility (IOPCITunnelCompatible) checks on macOS 10.13.4+.
@goalque for support for NVIDIA eGFX on macOS 10.13.4+.
@rgov for Ti82 Thunderbolt patches - adapted for Lilu by @mac_editor.

jcbrtl / kryptonite