diff --git a/man/systemd-stub.xml b/man/systemd-stub.xml
index 337759a0c3..184b10bc88 100644
--- a/man/systemd-stub.xml
+++ b/man/systemd-stub.xml
@@ -162,30 +162,32 @@
system extension images is measured into TPM PCR 13 (if a TPM is present).
Similarly, files
- foo.efi.extra.d/*.addon.efi
- are loaded and verified as PE binaries, and a .cmdline section is parsed from them.
- In case Secure Boot is enabled, these files will be validated using keys in UEFI DB, Shim's DB or
- Shim's MOK, and will be rejected otherwise. Additionally, if the both the addon and the UKI contain a
- a .uname section, the addon will be rejected if they do not exactly match. It is
+ foo.efi.extra.d/*.addon.efi are loaded and verified as
+ PE binaries, and a .cmdline section is parsed from them. Addons are supposed to be
+ used to pass additional kernel command line parameters or Devicetree blobs, regardless of the kernel
+ image being booted, for example to allow platform vendors to ship platform-specific
+ configuration.
+
+ In case Secure Boot is enabled, these files will be validated using keys in UEFI DB, Shim's DB or
+ Shim's MOK, and will be rejected otherwise. Additionally, if the both the addon and the UKI contain a a
+ .uname section, the addon will be rejected if they do not match exactly. It is
recommended to always add a .sbat section to all signed addons, so that they may be
revoked with a SBAT policy update, without requiring blocklisting via DBX/MOKX. The
- ukify1 tool will
- add a SBAT policy by default if none is passed when building addons. For more information on SBAT see
- Shim's documentation.
- Addons are supposed to be used to pass additional kernel command line parameters or Devicetree blobs,
- regardless of the kernel image being booted, for example to allow platform vendors to ship
- platform-specific configuration. The loaded command line addon files are sorted, loaded, and measured
- into TPM PCR 12 (if a TPM is present) and appended to the kernel command line. UKI command line options
- are listed first, then options from addons in /loader/addons/*.addon.efi, and
- finally UKI-specific addons. Device tree blobs are loaded and measured following the same algorithm.
- Addons are always loaded in the same order based on the filename, so that, given the same set of
- addons, the same set of measurements can be expected in PCR12. However, note that the filename is not
- protected by the PE signature, and as such an attacker with write access to the ESP could potentially
- rename these files to change the order in which they are loaded, in a way that could alter the
- functionality of the kernel, as some options might be order dependent. If you sign such addons, you
- should pay attention to the PCR12 values and make use of an attestation service so that improper use
- of your signed addons can be detected and dealt with using one of the aforementioned revocation
- mechanisms.
+ ukify1 tool will add
+ a SBAT policy by default if none is passed when building addons. For more information on SBAT see
+ Shim documentation.
+
+ Addon files are sorted, loaded, and measured into TPM PCR 12 (if a TPM is present) and appended
+ to the kernel command line. UKI command line options are listed first, then options from addons in
+ /loader/addons/*.addon.efi, and finally UKI-specific addons. Device tree blobs are
+ loaded and measured following the same algorithm. Addons are always loaded in the same order based on
+ the filename, so that, given the same set of addons, the same set of measurements can be expected in
+ PCR12. However, note that the filename is not protected by the PE signature, and as such an attacker
+ with write access to the ESP could potentially rename these files to change the order in which they are
+ loaded, in a way that could alter the functionality of the kernel, as some options might be
+ order-dependent. If you sign such addons, you should pay attention to the PCR12 values and make use of
+ an attestation service so that improper use of your signed addons can be detected and dealt with using
+ one of the aforementioned revocation mechanisms.
Files /loader/credentials/*.cred are packed up in a
cpio archive and placed in the /.extra/global_credentials/