Merge pull request #1195 from Dasharo/fusing_instructions

Fusing instructions

Author: wiktormowinski

docs/dasharo-tools-suite/documentation/features.md

@@ -2,34 +2,42 @@
 
 This section describes the functionality of the Dasharo Tools Suite. These are:
 
-* [DTS available commands](#available-commands)
-* [Dasharo zero-touch initial deployment](#dasharo-zero-touch-initial-deployment),
-* [HCL Report](#hcl-report),
-* [Firmware update](#firmware-update),
-    + [Local firmware update](#local-firmware-update),
-* [EC transition](#ec-transition),
-* [EC update](#ec-update),
-* [additional features](#additional-features),
-    + [run commands from iPXE shell automatically](#run-commands-from-ipxe-shell-automatically),
-    + [run DTS using VentoyOS](#run-dts-using-ventoyos).
+- [Features](#features)
+    + [Available Commands](#available-commands)
+    + [Dasharo zero-touch initial deployment (i.e. DZTID)](#dasharo-zero-touch-initial-deployment-ie-dztid)
+    + [HCL Report](#hcl-report)
+        - [HCL Report correctness](#hcl-report-correctness)
+        - [HCL Report Using an External Firmware Binary](#hcl-report-using-an-external-firmware-binary)
+        - [BIOS backup](#bios-backup)
+    + [Firmware update](#firmware-update)
+        - [Firmware Update Mode](#firmware-update-mode)
+        - [Local firmware update](#local-firmware-update)
+        - [Update issues](#update-issues)
+    + [EC transition](#ec-transition)
+    + [EC update](#ec-update)
+    + [Fusing the device vendor keys](#fusing-the-device-vendor-keys)
+    + [Verify Intel Boot Guard key](#verify-intel-boot-guard-key)
+    + [Additional features](#additional-features)
+        - [Run commands from iPXE shell automatically](#run-commands-from-ipxe-shell-automatically)
+        - [Run DTS using VentoyOS](#run-dts-using-ventoyos)
 
 ## Available Commands
 
 When DTS is started, it has following options for the user to choose from:
 
-* **1)** [Dasharo HCL Report](#hcl-report) - generate Hardware
+- **1)** [Dasharo HCL Report](#hcl-report) - generate Hardware
   Compatibility List Report
-* **2)** [Update Dasharo Firmware](#firmware-update) or [Install Dasharo
+- **2)** [Update Dasharo Firmware](#firmware-update) or [Install Dasharo
   Firmware](#dasharo-zero-touch-initial-deployment)
-* **3)** [Restore Firmware from Dasharo HCL Report](#update-issues)
-* **4)** [Load your DPP
+- **3)** [Restore Firmware from Dasharo HCL Report](#update-issues)
+- **4)** [Load your DPP
     keys](../../osf-trivia-list/dts.md#how-can-i-use-my-dasharo-pro-package-credentials)
     \- Load your Dasharo Pro Package (DPP) keys
-* **R** Reboot
-* **P** Poweroff
-* **S** Enter shell
-* **K** Launch SSH Server
-* **L** [Enable sending DTS
+- **R** Reboot
+- **P** Poweroff
+- **S** Enter shell
+- **K** Launch SSH Server
+- **L** [Enable sending DTS
   logs](../../osf-trivia-list/dts.md#how-can-i-help-the-support-team-diagnose-my-problem-faster)
 
 ## Dasharo zero-touch initial deployment (i.e. DZTID)
@@ -60,20 +68,20 @@ version of Dasharo, which we provide for given hardware.
 
 This feature is supported on the following platforms:
 
-* ASUS KGPE-D16,
-* Dell OptiPlex 7010/9010,
-* MSI PRO Z690-A DDR4,
-* MSI PRO Z690-A DDR5,
-* MSI PRO Z790-P DDR4,
-* MSI PRO Z790-P DDR5,
-* NovaCustom NV4x (only 11th Gen (Tiger Lake)),
-* NovaCustom NS5x/7x (only 11th Gen (Tiger Lake)),
-* ODROID-H4+.
+- ASUS KGPE-D16,
+- Dell OptiPlex 7010/9010,
+- MSI PRO Z690-A DDR4,
+- MSI PRO Z690-A DDR5,
+- MSI PRO Z790-P DDR4,
+- MSI PRO Z790-P DDR5,
+- NovaCustom NV4x (only 11th Gen (Tiger Lake)),
+- NovaCustom NS5x/7x (only 11th Gen (Tiger Lake)),
+- ODROID-H4+.
 
 And partially (only EC firmware flashing) on:
 
-* NovaCustom V540TU/TNx,
-* NovaCustom V560TU/TNx.
+- NovaCustom V540TU/TNx,
+- NovaCustom V560TU/TNx.
 
 ## HCL Report
 
@@ -185,11 +193,11 @@ contribute information about your hardware configuration.
 
 Please consider the following options depending on your situation:
 
-* **YES** - If you decide to contribute, you can always [get back to
+- **YES** - If you decide to contribute, you can always [get back to
   us](https://www.dasharo.com/pages/contact/) and ask about BIOS backup, which
   we will provide after simple verification that you are the owner of the
   hardware.
-* **NO (default)** - If you decide to not contribute, your situation depends on
+- **NO (default)** - If you decide to not contribute, your situation depends on
   the boot method you used to execute DTS:
     + **Network Boot** - please note that Dasharo booted over iPXE assumes no
       storage available, so the report, and your BIOS backup are stored in
@@ -412,7 +420,7 @@ firmware.
 DTS allows to update open-source Embedded Controller firmware to the newer
 version. This is how we can achieve that.
 
-* Retrieve information about your current EC.
+- Retrieve information about your current EC.
 
     ```bash
     dasharo_ectool info
@@ -426,10 +434,10 @@ version. This is how we can achieve that.
     version: 2022-08-16_c12ff1a
     ```
 
-* Download the newest version of Embedded Controller firmware.
-* Plug in power supply, without it, flashing EC is not possible as losing power
+- Download the newest version of Embedded Controller firmware.
+- Plug in power supply, without it, flashing EC is not possible as losing power
   may cause in damaged firmware.
-* Flash Embedded Controller firmware internally.
+- Flash Embedded Controller firmware internally.
 
     ```bash
     dasharo_ectool flash ec_file.rom
@@ -457,10 +465,10 @@ version. This is how we can achieve that.
 
   > Note: this is example output, versions may differ
 
-* Computer will shut down automatically.
-* Power on your computer. Booting process may take a while.
-* After boot, choose option `S` to drop to Shell.
-* Retrieve information about your updated EC.
+- Computer will shut down automatically.
+- Power on your computer. Booting process may take a while.
+- After boot, choose option `S` to drop to Shell.
+- Retrieve information about your updated EC.
 
     ```bash
     dasharo_ectool info
@@ -474,6 +482,40 @@ version. This is how we can achieve that.
     version: 2022-08-31_cbff21b
     ```
 
+## Fusing the device vendor keys
+
+DTS can be used to fuse the device vendor keys onto the SoC to enable
+the Dasharo TrustRoot feature.
+
+!!! warning
+
+    This operation is irreversible and can seriously hinder the devices
+    usability for the sake of security. Make sure you understand the
+    consequences before continuing.
+    Refer to [Glossary / Dasharo TrustRoot](../../glossary.md#dasharo-trustroot)
+    for more details.
+
+The decision to fuse the keys requires the user to explicitly opt-in.
+Updating the firmware will never fuse the device on its own.
+
+To perform fusing procedure:
+
+1. Make sure a power supply is connected to the device if it is battery powered
+2. Make sure the device has Dasharo firmware and the support for Dasharo
+   TrustRoot.
+3. Boot Dasharo Tools Suite and choose the option `7) Fuse platform`.
+   ![DTS Choosing the option to fuse the device](../images/dts-fusing-1.png)
+    1. If you are not using the newest Dasharo version available, you will be
+    prompted to update Dasharo first. Proceed with [Firmware Update](#firmware-update)
+   and try again.
+4. You will be prompted to confirm that you want to fuse the device. Select `y`
+   to continue or `n` to cancel.
+5. From now on the rest of the procedure will look like a normal firmware update.
+   You will be asked to verify the device model and the firmware version about
+   to be installed along the fusing procedure.
+6. After everything is done, your device will reboot.
+   ![DTS All the confirmations for fusing the device](../images/dts-fusing-2.png)
+
 ## Verify Intel Boot Guard key
 
 It's possible to verify which keys currently running firmware is signed with:
@@ -506,11 +548,11 @@ You can use the
 [local-ipxe-server.sh](https://github.com/Dasharo/meta-dts/blob/main/scripts/local-ipxe-server.sh)
 script for that. What it does is:
 
-* automatically download the latest version of DTS artifacts needed for iPXE
+- automatically download the latest version of DTS artifacts needed for iPXE
   boot,
-* creates a `dts.ipxe` bootchain file, which will boot DTS and also run your
+- creates a `dts.ipxe` bootchain file, which will boot DTS and also run your
   custom script,
-* creates a simple, python-based HTTP server, from which you will be able to
+- creates a simple, python-based HTTP server, from which you will be able to
   boot DTS.
 
 > Note: This functionality is available from version 1.2.19.

docs/dasharo-tools-suite/images/dts-fusing-1.png

@@ -0,0 +1,44 @@
+# Dasharo TrustRoot - Fusing vendor keys to the CPU
+
+In order to take use of the Dasharo TrustRoot feature on supported Devices,
+the device vendor key hashes need to be physically burned into the SoC.
+
+This document describes the steps for fusing vendor keys into your device.
+For more details check [Glossary / Dasharo TrustRoot](../glossary.md#dasharo-trustroot)
+
+!!! warning
+
+    Fusing device vendor keys is a feature targeted for advanced security
+    freaks. This operation permanently modifies your CPU. Reverting it
+    is only possible by replacing the CPU in the device.
+    Fusing vendor keys onto your CPU makes it impossible to:
+
+    - Use custom firmware not authorized by the vendor
+    - Update the firmware to a custom one if the support for your device ends
+
+    Be careful and make sure you understand the consequences before
+    proceeding with fusing your device.
+
+## Fusing the device vendor keys using Dasharo Tools Suite
+
+It's the recommended way of fusing your device. For details refer
+to [Dasharo Tools Suite documentation](../dasharo-tools-suite/documentation/features.md#fusing-the-device-vendor-keys)
+
+## Fusing the device using an EOM capsule (ADVANCED!)
+
+!!! warning
+
+    This method does not include any confirmations and guards from fusing the
+    device by a mistake. It is __NOT RECOMMENDED__ to perform the fusing
+    using a manual capsule update described here. Please consider doing it
+    [using DTS](#fusing-the-device-vendor-keys-using-dasharo-tools-suite)
+    instead.
+
+1. Locate the EOM capsule file of the desired Dasharo version. EOM firmware is
+   marked with `.eom` suffix, like `novacustom_v56x_mtl_igpu_v1.0.0_btg_provisioned.cap.eom`.
+   Make sure the firmware version is equal or higher than the currently used.
+2. Boot Dasharo Tools Suite. On how to, refer to [Running DTS](../dasharo-tools-suite/documentation/running.md)
+3. Enter the shell by pressing the `S` key as instructed in the main screen.
+4. Get the capsule file onto the running DTS by any means: `wget`, `scp` etc.
+5. Run `cat <your_eom_capsule_file> > /dev/efi_capsule_loader` to load the capsule.
+6. Reboot the device to perform the capsule update and fuse the device in the process.

docs/dasharo-tools-suite/images/dts-fusing-2.png

@@ -457,6 +457,7 @@ nav:
       - 'Capsule updates': guides/capsule-update.md
       - 'Flashing custom firmware': guides/firmware-reflash.md
       - 'Firmware signing for vboot': guides/vboot-signing.md
+      - 'Dasharo TrustRoot Fusing': guides/cpu-fusing.md
       - 'Dasharo Reviewers Guide': guides/dasharo-reviewers-guide.md
       - 'Verifying signatures': guides/signature-verification.md
       - 'Verifying reproducible builds': guides/reproducible-build-verification.md