OpenNetworkBoot: Add PXE and HTTP(S) Boot support

acidanthera · Nov 20, 2024 · 51089ad · 51089ad
1 parent 5d6759c
commit 51089ad
Show file tree

Hide file tree

Showing 36 changed files with 3,507 additions and 623 deletions.
diff --git a/Changelog.md b/Changelog.md
@@ -6,6 +6,8 @@ OpenCore Changelog
 - Added Arrow Lake CPU detection
 - Fixed Raptor Lake CPU detection
 - Supported booting with TuneD in Fedora 41 in OpenLinuxBoot
+- Added OpenNetworkBoot driver to support HTTP(S) and PXE boot
+- Supported DMG loading and verification (e.g. macOS Recovery) over HTTP(S) boot
 
 #### v1.0.2
 - Fixed error in macrecovery when running headless, thx @mkorje

diff --git a/Docs/Configuration.tex b/Docs/Configuration.tex
@@ -4119,6 +4119,7 @@ \subsection{Debug Properties}\label{miscdebugprops}
   \item \texttt{HDA} --- AudioDxe
   \item \texttt{KKT} --- KeyTester
   \item \texttt{LNX} --- OpenLinuxBoot
+  \item \texttt{NTBT} --- OpenNetworkBoot
   \item \texttt{MMDD} --- MmapDump
   \item \texttt{OCPAVP} --- PavpProvision
   \item \texttt{OCRST} --- ResetSystem
@@ -6579,6 +6580,9 @@ \subsection{Drivers}\label{uefidrivers}
 & \hyperref[uefilinux]{OpenCore plugin} implementing \texttt{OC\_BOOT\_ENTRY\_PROTOCOL}
   to allow direct detection and booting of Linux distributions from OpenCore, without
   chainloading via GRUB. \\
+\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{OpenNetworkBoot}}\textbf{*}
+& \hyperref[uefipxe]{OpenCore plugin} implementing \texttt{OC\_BOOT\_ENTRY\_PROTOCOL}
+  to show available PXE and HTTP(S) boot options on the OpenCore boot menu. \\
 \href{https://github.com/acidanthera/OpenCorePkg}{\texttt{OpenNtfsDxe}}\textbf{*}
 & New Technologies File System (NTFS) read-only driver.
   NTFS is the primary file system for Microsoft Windows versions that are based on Windows NT. \\
@@ -7092,9 +7096,141 @@ \subsubsection{Additional information}
 therefore \texttt{efibootmgr} rather than \texttt{bootctl} must be used for any low-level Linux command line interaction
 with the boot menu.
 
+\subsection{OpenNetworkBoot}\label{uefipxe}
+
+OpenNetworkBoot is an OpenCore plugin implementing \texttt{OC\_BOOT\_ENTRY\_PROTOCOL}.
+It enables PXE and HTTP(S) Boot options in the OpenCore menu if these
+are supported by the underlying firmware, or if the required network boot drivers
+have been loaded using OpenCore.
+
+It has additional support for loading \texttt{.dmg} files and their associated
+\texttt{.chunklist} file over HTTP(S) Boot, allowing macOS recovery to be
+started over HTTP(S) Boot: if either extension is seen in the HTTP(S) Boot URI
+then the other file of the pair is automatically loaded as well, and both are
+passed to OpenCore to verify and boot from the DMG file.
+
+PXE Boot is already supported on most firmware, so in most cases PXE Boot entries
+should appear as soon as the driver is loaded. Using the additional network boot
+drivers provided with OpenCore, when needed, HTTP(S) Boot should be available on
+most firmware even if not natively supported.
+
+Detailed information about the available network boot drivers and how to configure
+PXE and HTTP(S) Boot is provided on
+\href{https://github.com/acidanthera/OpenCorePkg/blob/master/Platform/OpenNetworkBoot/README.md}{this page}.
+
+The following configuration options may be specified in the \texttt{Arguments} section for this driver:
+
+\begin{itemize}
+  \item \texttt{-4} - Boolean flag, enabled if present. \medskip
+
+  If specified enable IPv4 for PXE and HTTP(S) Boot. Disable IPV6
+  unless the \texttt{-6} flag is also present. If neither flag is
+  present, both are enabled by default. \medskip
+
+  \item \texttt{-6} - Boolean flag, enabled if present. \medskip
+
+  If specified enable IPv6 for PXE and HTTP(S) Boot. Disable IPV4
+  unless the \texttt{-4} flag is also present. If neither flag is
+  present, both are enabled by default. \medskip
+
+  \item \texttt{-{}-aux} - Boolean flag, enabled if present. \medskip
+
+  If specified the driver will generate auxiliary boot entries. \medskip
+
+  \item \texttt{-{}-delete-all-certs[:\{OWNER\_GUID\}]} - Default: not set. \medskip
+
+  If specified, delete all certificates present for \texttt{OWNER\_GUID}.
+  \texttt{OWNER\_GUID} is optional, and will default to all zeros if not specified. \medskip
+
+  \item \texttt{-{}-delete-cert[:\{OWNER\_GUID\}]="\{cert-text\}"} - Default: not set. \medskip
+
+  If specified, delete the given certificate(s) for HTTPS Boot. The certificate(s) can be specified
+  as a multi-line PEM value between double quotes.
+  \texttt{OWNER\_GUID} is optional, and will default to all zeros if not specified.
+  A single PEM file can contain one or more certicates.
+  Multiple instances of this option can be used to delete multiple different
+  PEM files, if required.
+
+  \item \texttt{-{}-enroll-cert[:\{OWNER\_GUID\}]="\{cert-text\}"} - Default: not set. \medskip
+
+  If specified, enroll the given certificate(s) for HTTPS Boot. The certificate(s) can be specified
+  as a multi-line PEM value between double quotes.
+  \texttt{OWNER\_GUID} is optional, and will default to all zeros if not specified.
+  A single PEM file can contain one or more certicates.
+  Multiple instances of this option can be used to enroll multiple different
+  PEM files, if required. \medskip
+
+  \item \texttt{-{}-http} - Boolean flag, enabled if present. \medskip
+
+  If specified enable HTTP(S) Boot. Disable PXE Boot unless
+  the \texttt{-{}-pxe} flag is also present. If neither flag is
+  present, both are enabled by default. \medskip
+
+  \item \texttt{-{}-https} - Boolean flag, enabled if present. \medskip
+
+  If enabled, allow only \texttt{https://} URIs for HTTP(S) Boot.
+  Additionally has the same behaviour as the \texttt{-{}-http} flag. \medskip
+
+  \item \texttt{-{}-pxe} - Boolean flag, enabled if present. \medskip
+
+  If specified enable PXE Boot, and disable HTTP(S) Boot unless
+  the \texttt{-{}-http} or \texttt{-{}-https} flags are present.
+  If none of these flags are present, both PXE and HTTP(S) Boot are
+  enabled by default. \medskip
+
+  \item \texttt{-{}-uri} - String value, no default. \medskip
+
+  If present, specify the URI to use for HTTP(S) Boot. If not present then
+  DHCP boot options must be enabled on the network in order for HTTP(S)
+  Boot to know what to boot.
+
+\end{itemize} \medskip
+
+\subsubsection{OpenNetworkBoot Certificate Management}
+
+Certificates are enrolled to NVRAM storage, therefore once
+a certificate has been enrolled, it will remain enrolled even if the \texttt{-{}-enroll-cert} config
+option is removed. \texttt{-{}-delete-cert} or \texttt{-{}-delete-all-certs}
+should be used to remove enrolled certificates.
+
+Checking for certificate presence by the \texttt{-{}-enroll-cert}
+and \texttt{-{}-delete-cert} options uses the simple algorithm
+of matching by exact file contents, not by file meaning. The intended
+usage is to leave an \texttt{-{}-enroll-cert} option present in the config
+file until it is time to delete it, e.g. after another more up-to-date
+\texttt{-{}-enroll-cert} option has been added and tested. At this point
+the user can change \texttt{-{}-enroll-cert} to \texttt{-{}-delete-cert}
+for the old certificate. \medskip
+
+Certificate options are processed one at a time, in
+order, and each will potentially make changes to the certificate NVRAM storage.
+However each option will not change the NVRAM store if it is already correct
+for the option at that point in time (e.g. will not enroll a certificate if it is
+already enrolled).
+Avoid combinations such as \texttt{-{}-delete-all-certs} followed by
+\texttt{-{}-enroll-cert}, as this will modify the NVRAM certificate
+storage twice on every boot. However a combination such as
+\texttt{-{}-delete-cert="\{certA-text\}"} followed by \texttt{-{}-enroll-cert="\{certB-text\}"}
+(with \texttt{certA-text} and \texttt{certB-text} different) is safe,
+because certA will only be deleted if it is present
+and certB will only be added if it is not present, therefore no
+NVRAM changes will be made on the second and subsequent boots
+with these options.
+
+In some cases (such as OVMF with https:// boot support) the
+\texttt{OpenNetworkBoot} certificate configuration options manage the same
+certificates as those seen in the firmware UI. In other cases of vendor customised
+HTTPS Boot firmware, the certificates managed by this driver will be
+separate from those managed by firmware.
+
+When using the debug version of this driver, the OpenCore debug log includes \texttt{NTBT:} entries
+that show which certificates are enrolled and removed by these options, and which
+certificates are present after all certificate configuration options have been processed.
+
 \subsection{Other Boot Entry Protocol drivers}
 
-In addition to the \hyperref[uefilinux]{OpenLinuxBoot} plugin, the following \texttt{OC\_BOOT\_ENTRY\_PROTOCOL}
+In addition to the \hyperref[uefilinux]{OpenLinuxBoot} and \hyperref[uefipxe]{OpenNetworkBoot} plugins,
+the following \texttt{OC\_BOOT\_ENTRY\_PROTOCOL}
 plugins are made available to add optional, configurable boot entries to the OpenCore boot picker.
 
 \subsubsection{ResetNvramEntry}\label{uefiresetnvram}

diff --git a/Docs/Flavours.md b/Docs/Flavours.md
@@ -21,7 +21,7 @@ Icon pack authors are encouraged to provide only those icons for which there is
 
 In the case of macOS only, a flavour based on the detected OS version is applied automatically (as shown below), and the user does not normally need to override this.
 
-For icon pack authors, the **Apple** icon is recommended, **AppleRecovery** and **AppleTM** are suggested, all others are entirely optional.
+For icon pack authors, the **Apple** icon is recommended, **AppleRecv** and **AppleTM** are suggested, all others are entirely optional.
 
  - **Apple12:Apple** - Monterey (`Apple12.icns`)
  - **Apple11:Apple** - Big Sur (`Apple11.icns`)
@@ -155,18 +155,31 @@ If providing `NVRAMTool.icns`, it should be themed so that it could be applied t
  - **ResetNVRAM:NVRAMTool** - Reset NVRAM tool  (`ResetNVRAM.icns`)
    - This is the recommended flavour, used for the entry created by the `ResetNvramEntry.efi` driver.
    - As another example of how flavours work: **ResetNVRAM:NVRAMTool** will look for `ResetNVRAM.icns`, then `NVRAMTool.icns` (and then, by OC default behaviour, `Tool.icns` then `HardDrive.icns`)
-   - **Note**: Including **ResetNVRAM** anywhere in a user flavour triggers picker audio-assist and builtin label support for "Reset NVRAM"
+   - **Note**: Including **ResetNVRAM** anywhere in a flavour triggers picker audio-assist and builtin label support for "Reset NVRAM"
  - **ToggleSIP:NVRAMTool** - Icon themed for Toggle SIP tool  (`ToggleSIP.icns`)
  - **ToggleSIP_Enabled:ToggleSIP:NVRAMTool** - Icon themed for Toggle SIP tool when SIP is enabled (system is protected)
  - **ToggleSIP_Disabled:ToggleSIP:NVRAMTool** - Icon themed for Toggle SIP tool when SIP is disabled (system is unprotected)
-   - **Note**: Including **ToggleSIP_Enabled** or **ToggleSIP_Disabled** anywhere in a user flavour triggers picker audio-assist and builtin label support for the two states of the Toggle SIP menu entry
+   - **Note**: Including **ToggleSIP_Enabled** or **ToggleSIP_Disabled** anywhere in a flavour triggers picker audio-assist and builtin label support for the two states of the Toggle SIP menu entry
+
+### Network Boot
+
+`OpenNetworkBoot.efi` uses the following flavours:
+
+ - **HttpBoot4:HttpBoot:NetworkBoot** - IPv4 HTTP(S) Boot
+ - **HttpBoot6:HttpBoot:NetworkBoot** - IPv6 HTTP(S) Boot
+ - **PxeBoot4:PxeBoot:NetworkBoot** - IPv4 PXE Boot
+ - **PxeBoot6:PxeBoot:NetworkBoot** - IPv6 PXE Boot
+
+If none of these icons are available, network boot is treated like an external OS, so the fallbacks are **Other** followed by **HardDrive**.
+
+ - **Note**: Including **NetworkBoot** anywhere in a flavour triggers picker audio-assist and builtin label support for "Network Boot"
 
 ### Other Tools
 
 A list of other known tools which are common enough that some icon pack artists may wish to provide a standard icon for them:
 
- - **FirmwareSettings** - A boot menu entry for accessing firmware settings (`FirmwareSettings.icns`)
-   - **Note**: Including **FirmwareSettings** anywhere in a user flavour triggers picker audio-assist and builtin label support for "Firmware Settings"
+ - **FirmwareSettings** - A boot menu entry for accessing firmware settings, such as generated by `FirmwareSettingsEntry.efi` (`FirmwareSettings.icns`)
+   - **Note**: Including **FirmwareSettings** anywhere in a flavour triggers picker audio-assist and builtin label support for "Firmware Settings"
  - **MemTest** - A system memory testing tool such as that available from [memtest86.com](https://www.memtest86.com/) (`MemTest.icns`)
 
 ## Bootloaders
@@ -198,6 +211,7 @@ Provided by OcBinaryData. Used automatically by OC in some circumstances, if pro
  - **ExtAppleTM** - Apple Time Machine (on external drive) (fallback: **ExtHardDrive**)
  - **Shell** - Shell tool (fallback: **Tool**)
  - **Tool** - Generic tool (fallback: **HardDrive**)
+ - **Other** - Other OS (fallback: **HardDrive**)
  - **Windows** - Microsoft Windows (fallback: **HardDrive**)
 
 ### Additional Optional

diff --git a/Docs/Sample.plist b/Docs/Sample.plist
@@ -1697,6 +1697,30 @@
 				<key>Path</key>
 				<string>Ext4Dxe.efi</string>
 			</dict>
+			<dict>
+				<key>Arguments</key>
+				<string></string>
+				<key>Comment</key>
+				<string></string>
+				<key>Enabled</key>
+				<false/>
+				<key>LoadEarly</key>
+				<false/>
+				<key>Path</key>
+				<string>RngDxe.efi</string>
+			</dict>
+			<dict>
+				<key>Arguments</key>
+				<string></string>
+				<key>Comment</key>
+				<string></string>
+				<key>Enabled</key>
+				<false/>
+				<key>LoadEarly</key>
+				<false/>
+				<key>Path</key>
+				<string>Hash2DxeCrypto.efi</string>
+			</dict>
 			<dict>
 				<key>Arguments</key>
 				<string></string>
@@ -1781,6 +1805,66 @@
 				<key>Path</key>
 				<string>Udp4Dxe.efi</string>
 			</dict>
+			<dict>
+				<key>Arguments</key>
+				<string></string>
+				<key>Comment</key>
+				<string></string>
+				<key>Enabled</key>
+				<false/>
+				<key>LoadEarly</key>
+				<false/>
+				<key>Path</key>
+				<string>Mtftp4Dxe.efi</string>
+			</dict>
+			<dict>
+				<key>Arguments</key>
+				<string></string>
+				<key>Comment</key>
+				<string></string>
+				<key>Enabled</key>
+				<false/>
+				<key>LoadEarly</key>
+				<false/>
+				<key>Path</key>
+				<string>Dhcp6Dxe.efi</string>
+			</dict>
+			<dict>
+				<key>Arguments</key>
+				<string></string>
+				<key>Comment</key>
+				<string></string>
+				<key>Enabled</key>
+				<false/>
+				<key>LoadEarly</key>
+				<false/>
+				<key>Path</key>
+				<string>Ip6Dxe.efi</string>
+			</dict>
+			<dict>
+				<key>Arguments</key>
+				<string></string>
+				<key>Comment</key>
+				<string></string>
+				<key>Enabled</key>
+				<false/>
+				<key>LoadEarly</key>
+				<false/>
+				<key>Path</key>
+				<string>Udp6Dxe.efi</string>
+			</dict>
+			<dict>
+				<key>Arguments</key>
+				<string></string>
+				<key>Comment</key>
+				<string></string>
+				<key>Enabled</key>
+				<false/>
+				<key>LoadEarly</key>
+				<false/>
+				<key>Path</key>
+				<string>Mtftp6Dxe.efi</string>
+			</dict>
 			<dict>
 				<key>Arguments</key>
 				<string></string>
@@ -1793,6 +1877,18 @@
 				<key>Path</key>
 				<string>TcpDxe.efi</string>
 			</dict>
+			<dict>
+				<key>Arguments</key>
+				<string></string>
+				<key>Comment</key>
+				<string></string>
+				<key>Enabled</key>
+				<false/>
+				<key>LoadEarly</key>
+				<false/>
+				<key>Path</key>
+				<string>UefiPxeBcDxe.efi</string>
+			</dict>
 			<dict>
 				<key>Arguments</key>
 				<string></string>
@@ -1841,6 +1937,30 @@
 				<key>Path</key>
 				<string>HttpBootDxe.efi</string>
 			</dict>
+			<dict>
+				<key>Arguments</key>
+				<string></string>
+				<key>Comment</key>
+				<string></string>
+				<key>Enabled</key>
+				<false/>
+				<key>LoadEarly</key>
+				<false/>
+				<key>Path</key>
+				<string>TlsDxe.efi</string>
+			</dict>
+			<dict>
+				<key>Arguments</key>
+				<string></string>
+				<key>Comment</key>
+				<string></string>
+				<key>Enabled</key>
+				<false/>
+				<key>LoadEarly</key>
+				<false/>
+				<key>Path</key>
+				<string>RamDiskDxe.efi</string>
+			</dict>
 			<dict>
 				<key>Arguments</key>
 				<string></string>