Merge branch 'acidanthera:master' into YamingNetwork

Changelog.md

@@ -7,6 +7,8 @@ OpenCore Changelog
 - Fixed Raptor Lake CPU detection
 - Supported booting with TuneD in Fedora 41 in OpenLinuxBoot
 - Fixed failure of vault `sign.command` to insert signature in correct location in some circumstances
+- 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

Docs/Configuration.md5

@@ -1 +1 @@
-fa42399c09fbdc260b41745484b4a752
+02c9a039d73ac5b42665ccb8066ae9fa

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
@@ -6574,6 +6575,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. \\
@@ -7087,9 +7091,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}

Docs/Differences/Differences.tex

@@ -1,7 +1,7 @@
 \documentclass[]{article}
 %DIF LATEXDIFF DIFFERENCE FILE
 %DIF DEL PreviousConfiguration.tex   Tue Nov 26 03:15:30 2024
-%DIF ADD ../Configuration.tex        Tue Nov 26 03:15:30 2024
+%DIF ADD ../Configuration.tex        Sat Nov 30 18:40:01 2024
 
 \usepackage{lmodern}
 \usepackage{amssymb,amsmath}
@@ -4179,7 +4179,8 @@ \subsection{Debug Properties}\label{miscdebugprops}
   \item \texttt{HDA} --- AudioDxe
   \item \texttt{KKT} --- KeyTester
   \item \texttt{LNX} --- OpenLinuxBoot
-  \item \texttt{MMDD} --- MmapDump
+  \item \DIFaddbegin \texttt{\DIFadd{NTBT}} \DIFadd{--- OpenNetworkBoot
+  }\item \DIFaddend \texttt{MMDD} --- MmapDump
   \item \texttt{OCPAVP} --- PavpProvision
   \item \texttt{OCRST} --- ResetSystem
   \item \texttt{OCUI} --- OpenCanopy
@@ -6643,7 +6644,10 @@ \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{OpenNtfsDxe}}\textbf{*}
+\DIFaddbegin \href{https://github.com/acidanthera/OpenCorePkg}{\texttt{\DIFadd{OpenNetworkBoot}}}\textbf{\DIFadd{*}}
+& \hyperref[uefipxe]{OpenCore plugin} \DIFadd{implementing }\texttt{\DIFadd{OC\_BOOT\_ENTRY\_PROTOCOL}}
+  \DIFadd{to show available PXE and HTTP(S) boot options on the OpenCore boot menu. }\\
+\DIFaddend \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. \\
 \href{https://github.com/acidanthera/OpenCorePkg}{\texttt{OpenUsbKbDxe}}\textbf{*}
@@ -7157,9 +7161,152 @@ \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{Other Boot Entry Protocol drivers}
+\DIFaddbegin \subsection{\DIFadd{OpenNetworkBoot}}\label{uefipxe}
 
-In addition to the \hyperref[uefilinux]{OpenLinuxBoot} plugin, the following \texttt{OC\_BOOT\_ENTRY\_PROTOCOL}
+\DIFadd{OpenNetworkBoot is an OpenCore plugin implementing }\texttt{\DIFadd{OC\_BOOT\_ENTRY\_PROTOCOL}}\DIFadd{.
+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.
+}
+
+\DIFadd{It has additional support for loading }\texttt{\DIFadd{.dmg}} \DIFadd{files and their associated
+}\texttt{\DIFadd{.chunklist}} \DIFadd{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.
+}
+
+\DIFadd{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.
+}
+
+\DIFadd{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}{\DIFadd{this page}}\DIFadd{.
+}
+
+\DIFadd{The following configuration options may be specified in the }\texttt{\DIFadd{Arguments}} \DIFadd{section for this driver:
+}
+
+\begin{itemize}
+  \item \texttt{\DIFadd{-4}} \DIFadd{- Boolean flag, enabled if present. }\medskip
+
+  \DIFadd{If specified enable IPv4 for PXE and HTTP(S) Boot. Disable IPV6
+  unless the }\texttt{\DIFadd{-6}} \DIFadd{flag is also present. If neither flag is
+  present, both are enabled by default. }\medskip
+
+  \item \texttt{\DIFadd{-6}} \DIFadd{- Boolean flag, enabled if present. }\medskip
+
+  \DIFadd{If specified enable IPv6 for PXE and HTTP(S) Boot. Disable IPV4
+  unless the }\texttt{\DIFadd{-4}} \DIFadd{flag is also present. If neither flag is
+  present, both are enabled by default. }\medskip
+
+  \item \texttt{\DIFadd{-}{}\DIFadd{-aux}} \DIFadd{- Boolean flag, enabled if present. }\medskip
+
+  \DIFadd{If specified the driver will generate auxiliary boot entries. }\medskip
+
+  \item \texttt{\DIFadd{-}{}\DIFadd{-delete-all-certs}[\DIFadd{:\{OWNER\_GUID\}}]} \DIFadd{- Default: not set. }\medskip
+
+  \DIFadd{If specified, delete all certificates present for }\texttt{\DIFadd{OWNER\_GUID}}\DIFadd{.
+  }\texttt{\DIFadd{OWNER\_GUID}} \DIFadd{is optional, and will default to all zeros if not specified. }\medskip
+
+  \item \texttt{\DIFadd{-}{}\DIFadd{-delete-cert}[\DIFadd{:\{OWNER\_GUID\}}]\DIFadd{="\{cert-text\}"}} \DIFadd{- Default: not set. }\medskip
+
+  \DIFadd{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{\DIFadd{OWNER\_GUID}} \DIFadd{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{\DIFadd{-}{}\DIFadd{-enroll-cert}[\DIFadd{:\{OWNER\_GUID\}}]\DIFadd{="\{cert-text\}"}} \DIFadd{- Default: not set. }\medskip
+
+  \DIFadd{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{\DIFadd{OWNER\_GUID}} \DIFadd{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{\DIFadd{-}{}\DIFadd{-http}} \DIFadd{- Boolean flag, enabled if present. }\medskip
+
+  \DIFadd{If specified enable HTTP(S) Boot. Disable PXE Boot unless
+  the }\texttt{\DIFadd{-}{}\DIFadd{-pxe}} \DIFadd{flag is also present. If neither flag is
+  present, both are enabled by default. }\medskip
+
+  \item \texttt{\DIFadd{-}{}\DIFadd{-https}} \DIFadd{- Boolean flag, enabled if present. }\medskip
+
+  \DIFadd{If enabled, allow only }\texttt{\DIFadd{https://}} \DIFadd{URIs for HTTP(S) Boot.
+  Additionally has the same behaviour as the }\texttt{\DIFadd{-}{}\DIFadd{-http}} \DIFadd{flag. }\medskip
+
+  \item \texttt{\DIFadd{-}{}\DIFadd{-pxe}} \DIFadd{- Boolean flag, enabled if present. }\medskip
+
+  \DIFadd{If specified enable PXE Boot, and disable HTTP(S) Boot unless
+  the }\texttt{\DIFadd{-}{}\DIFadd{-http}} \DIFadd{or }\texttt{\DIFadd{-}{}\DIFadd{-https}} \DIFadd{flags are present.
+  If none of these flags are present, both PXE and HTTP(S) Boot are
+  enabled by default. }\medskip
+
+  \item \texttt{\DIFadd{-}{}\DIFadd{-uri}} \DIFadd{- String value, no default. }\medskip
+
+  \DIFadd{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{\DIFadd{OpenNetworkBoot Certificate Management}}
+
+\DIFadd{Certificates are enrolled to NVRAM storage, therefore once
+a certificate has been enrolled, it will remain enrolled even if the }\texttt{\DIFadd{-}{}\DIFadd{-enroll-cert}} \DIFadd{config
+option is removed. }\texttt{\DIFadd{-}{}\DIFadd{-delete-cert}} \DIFadd{or }\texttt{\DIFadd{-}{}\DIFadd{-delete-all-certs}}
+\DIFadd{should be used to remove enrolled certificates.
+}
+
+\DIFadd{Checking for certificate presence by the }\texttt{\DIFadd{-}{}\DIFadd{-enroll-cert}}
+\DIFadd{and }\texttt{\DIFadd{-}{}\DIFadd{-delete-cert}} \DIFadd{options uses the simple algorithm
+of matching by exact file contents, not by file meaning. The intended
+usage is to leave an }\texttt{\DIFadd{-}{}\DIFadd{-enroll-cert}} \DIFadd{option present in the config
+file until it is time to delete it, e.g. after another more up-to-date
+}\texttt{\DIFadd{-}{}\DIFadd{-enroll-cert}} \DIFadd{option has been added and tested. At this point
+the user can change }\texttt{\DIFadd{-}{}\DIFadd{-enroll-cert}} \DIFadd{to }\texttt{\DIFadd{-}{}\DIFadd{-delete-cert}}
+\DIFadd{for the old certificate. }\medskip
+
+\DIFadd{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{\DIFadd{-}{}\DIFadd{-delete-all-certs}} \DIFadd{followed by
+}\texttt{\DIFadd{-}{}\DIFadd{-enroll-cert}}\DIFadd{, as this will modify the NVRAM certificate
+storage twice on every boot. However a combination such as
+}\texttt{\DIFadd{-}{}\DIFadd{-delete-cert="\{certA-text\}"}} \DIFadd{followed by }\texttt{\DIFadd{-}{}\DIFadd{-enroll-cert="\{certB-text\}"}}
+\DIFadd{(with }\texttt{\DIFadd{certA-text}} \DIFadd{and }\texttt{\DIFadd{certB-text}} \DIFadd{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.
+}
+
+\DIFadd{In some cases (such as OVMF with https:// boot support) the
+}\texttt{\DIFadd{OpenNetworkBoot}} \DIFadd{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.
+}
+
+\DIFadd{When using the debug version of this driver, the OpenCore debug log includes }\texttt{\DIFadd{NTBT:}} \DIFadd{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.
+}
+
+\DIFaddend \subsection{Other Boot Entry Protocol drivers}
+
+In addition to the \hyperref[uefilinux]{OpenLinuxBoot} \DIFdelbegin \DIFdel{plugin}\DIFdelend \DIFaddbegin \DIFadd{and }\hyperref[uefipxe]{OpenNetworkBoot} \DIFadd{plugins}\DIFaddend ,
+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}