V9.14.016.2026.06.06

Signed-off-by: Marc S. Weidner <msw@coresecret.dev>

config/hooks/live/zzzz_ciss_uki_install.hook.binary

@@ -9,10 +9,29 @@
 # SPDX-LicenseComment: This file is part of the CISS.debian.installer.secure framework.
 # SPDX-PackageName: CISS.debian.live.builder
 # SPDX-Security-Contact: security@coresecret.eu
+# shellcheck disable=SC2312
 set -Ceuo pipefail
 
+# Final live-build binary hook for CISS UKI installation. When the ciss-uki Secure Boot profile is active, this hook selects
+# the single signed CISS UKI, rebuilds the FAT EFI boot image with it as EFI/BOOT/BOOTX64.EFI, verifies the installed copy,
+# mirrors it into the ISO EFI tree when available, writes an installation manifest, and refuses private Secure Boot key
+# material in build artifact paths.
+
 declare TMP_DIR=""
 
+#######################################
+# Removes the temporary EFI image work directory if it is inside the expected Secure Boot output tree.
+# Globals:
+#   PWD
+#   TMP_DIR
+#   VAR_HANDLER_BUILD_DIR
+# Arguments:
+#   None
+# Returns:
+#   0: on success or when no temporary directory exists
+#   42: if the temporary directory is outside the expected cleanup root
+#   non-zero: if removal of the expected temporary directory fails under strict mode
+#######################################
 cleanup() {
   declare build_dir="${VAR_HANDLER_BUILD_DIR:-${PWD}}"
 
@@ -22,7 +41,7 @@ cleanup() {
         rm -rf -- "${TMP_DIR}"
         ;;
       *)
-        printf "\e[91m++++ ++++ ++++ ++++ ++++ ++++ ++ [FATAL] Refusing to clean unexpected temporary path: '%s'. \e[0m\n" "${TMP_DIR}" >&2
+        printf "\e[91m❌ Refusing to clean unexpected temporary path: '%s'. \e[0m\n" "${TMP_DIR}" >&2
         return 42
         ;;
     esac
@@ -30,14 +49,32 @@ cleanup() {
 
   return 0
 }
-trap cleanup EXIT
 
+#######################################
+# Prints a fatal error message and terminates the hook.
+# Globals:
+#   None
+# Arguments:
+#   1: Error message
+# Returns:
+#   42: always exits with failure
+#######################################
 die() {
   declare message="$1"
-  printf "\e[91m++++ ++++ ++++ ++++ ++++ ++++ ++ [FATAL] %s \e[0m\n" "${message}" >&2
+  printf "\e[91m❌ %s \e[0m\n" "${message}" >&2
   exit 42
 }
 
+#######################################
+# Checks whether a required command exists.
+# Globals:
+#   None
+# Arguments:
+#   1: Command name
+# Returns:
+#   0: on success
+#   42: if the command is missing
+#######################################
 require_command() {
   declare command_name="$1"
 
@@ -46,6 +83,17 @@ require_command() {
   return 0
 }
 
+#######################################
+# Checks whether a required file exists.
+# Globals:
+#   None
+# Arguments:
+#   1: File path
+#   2: Human-readable file description
+# Returns:
+#   0: on success
+#   42: if the file is missing
+#######################################
 require_file() {
   declare file_path="$1"
   declare description="$2"
@@ -55,6 +103,17 @@ require_file() {
   return 0
 }
 
+#######################################
+# Selects the single signed CISS UKI generated by the CISS UKI build hook.
+# Globals:
+#   None
+# Arguments:
+#   1: CISS UKI output directory
+#   2: Output variable name for the selected signed UKI path
+# Returns:
+#   0: on success
+#   42: if the UKI directory is missing or does not contain exactly one signed UKI
+#######################################
 select_signed_uki() {
   declare uki_dir="$1"
   declare output_var="$2"
@@ -73,6 +132,16 @@ select_signed_uki() {
   return 0
 }
 
+#######################################
+# Refuses private Secure Boot key material in generated artifact paths.
+# Globals:
+#   None
+# Arguments:
+#   None
+# Returns:
+#   0: on success
+#   42: if a private Secure Boot key is found below a guarded path
+#######################################
 guard_private_key_leaks() {
   declare -a guard_roots=(binary chroot config/includes.binary config/includes.chroot config/includes.installer)
   declare guard_root=""
@@ -93,6 +162,17 @@ guard_private_key_leaks() {
   return 0
 }
 
+#######################################
+# Mirrors the signed UKI into the ISO EFI tree as the removable-media bootloader when that tree exists.
+# Globals:
+#   None
+# Arguments:
+#   1: Signed UKI path
+#   2: Output variable name for the ISO EFI tree BOOTX64 path, or an empty value when no tree exists
+# Returns:
+#   0: on success, including when no ISO EFI tree exists
+#   non-zero: if directory creation or file installation fails under strict mode
+#######################################
 install_iso_tree_bootx64() {
   declare signed_uki="$1"
   declare output_var="$2"
@@ -109,9 +189,9 @@ install_iso_tree_bootx64() {
 
   if [[ -n "${iso_tree_bootx64}" ]]; then
     install -m 0644 "${signed_uki}" "${iso_tree_bootx64}"
-    printf "\e[92m++++ ++++ ++++ ++++ ++++ ++++ ++ [INFO] Mirrored signed UKI into ISO EFI tree: '%s'. \e[0m\n" "${iso_tree_bootx64}"
+    printf "\e[92m✅ Mirrored signed UKI into ISO EFI tree: '%s'. \e[0m\n" "${iso_tree_bootx64}"
   else
-    printf "\e[93m++++ ++++ ++++ ++++ ++++ ++++ ++ [WARN] No binary/EFI tree found; only EFI boot image was updated. \e[0m\n"
+    printf "\e[93m❌ No binary/EFI tree found; only EFI boot image was updated. \e[0m\n"
   fi
 
   printf -v "${output_var}" "%s" "${iso_tree_bootx64}"
@@ -119,6 +199,24 @@ install_iso_tree_bootx64() {
   return 0
 }
 
+#######################################
+# Installs the signed CISS UKI into the EFI boot image for the ciss-uki Secure Boot profile.
+# Globals:
+#   PWD
+#   SOURCE_DATE_EPOCH
+#   TMP_DIR
+#   VAR_CISS_SECUREBOOT_DIR
+#   VAR_CISS_SECUREBOOT_EFI_CERT
+#   VAR_CISS_SECUREBOOT_PROFILE
+#   VAR_HANDLER_BUILD_DIR
+#   VAR_WORKDIR
+# Arguments:
+#   None
+# Returns:
+#   0: on success or when the active Secure Boot profile does not require CISS UKI installation
+#   42: on explicit validation, comparison, or signature verification failure
+#   non-zero: if an external tool, installation command, or manifest write fails under strict mode
+#######################################
 main() {
   declare profile="${VAR_CISS_SECUREBOOT_PROFILE:-debian-shim}"
   declare build_dir="${VAR_HANDLER_BUILD_DIR:-${PWD}}"
@@ -142,11 +240,11 @@ main() {
   declare volid=""
 
   if [[ "${profile}" != "ciss-uki" ]]; then
-    printf "\e[92m++++ ++++ ++++ ++++ ++++ ++++ ++ [INFO] Secure Boot profile '%s'; skipping CISS UKI EFI installation. \e[0m\n" "${profile}"
+    printf "\e[92m✅ Secure Boot profile '%s'; skipping CISS UKI EFI installation. \e[0m\n" "${profile}"
     return 0
   fi
 
-  printf "\e[95m++++ ++++ ++++ ++++ ++++ ++++ ++ [INFO] Installing CISS signed UKI into EFI boot image ... \e[0m\n"
+  printf "\e[95m🧪 Installing CISS signed UKI into EFI boot image ... \e[0m\n"
 
   cd "${build_dir}"
 
@@ -191,7 +289,7 @@ main() {
   fi
   printf -v volid "%08x" "$((source_epoch % 4294967296))"
 
-  printf "\e[95m++++ ++++ ++++ ++++ ++++ ++++ ++ [INFO] Rebuilding EFI boot image with signed UKI as EFI/BOOT/BOOTX64.EFI. \e[0m\n"
+  printf "\e[95m🧪 Rebuilding EFI boot image with signed UKI as EFI/BOOT/BOOTX64.EFI. \e[0m\n"
   mkfs.msdos -C "${tmp_img}" "${blocks}" -i "${volid}" >/dev/null
   mmd -i "${tmp_img}" "::EFI"
   mmd -i "${tmp_img}" "::EFI/BOOT"
@@ -237,12 +335,13 @@ main() {
     sbverify --cert "${secureboot_cert}" "${extracted_uki}"
   } >| "${manifest}" 2>&1
 
-  printf "\e[92m++++ ++++ ++++ ++++ ++++ ++++ ++ [INFO] EFI image installation verification written to '%s'. \e[0m\n" "${manifest}"
-  printf "\e[92m++++ ++++ ++++ ++++ ++++ ++++ ++ [INFO] CISS signed UKI installed as EFI/BOOT/BOOTX64.EFI. \e[0m\n"
+  printf "\e[92m✅ EFI image installation verification written to '%s'. \e[0m\n" "${manifest}"
+  printf "\e[92m✅ CISS signed UKI installed as EFI/BOOT/BOOTX64.EFI. \e[0m\n"
 
   return 0
 }
 
 main "$@"
+cleanup
 exit 0
 # vim: number et ts=2 sw=2 sts=2 ai tw=128 ft=sh