docs(secure-boot): add troubleshooting steps

docs/src/content/docs/features/secure-boot.mdx

@@ -5,13 +5,13 @@ description: Learn how to set up secure boot on NixOS.
 
 import { Aside, Steps, Tabs, TabItem } from "@astrojs/starlight/components";
 
-## Setup
-
 <Aside type="caution">
   This feature is experimental. Use at your own risk, as it could brick your
-  device!
+  device.
 </Aside>
 
+## Setup
+
 <Steps>
 <ol>
 <li>
@@ -31,7 +31,12 @@ sudo nix run nixpkgs#sbctl create-keys
 </li>
 <li>
 
-Enable Secure Boot in your BIOS and enter Setup Mode or erase the Platform Keys.
+Enable Secure Boot in the UEFI and enter Setup Mode or erase the Platform Keys.
+
+</li>
+<li>
+
+Enroll the keys.
 
 <Tabs syncKey="nix-environment">
 <TabItem label="NixOS">
@@ -49,7 +54,7 @@ sudo nix run nixpkgs#sbctl enroll-keys -- --microsoft
 
 ## TPM disk unlock
 
-With secure boot in place, TPM can be used to automatically unlock encrypted partitions. After enabling this feature in the BIOS, setup your partitions. For each encrypted partition, run the following command by replacing `<encrypted-partion>` with its identifier, e.g. `nvme0n1p1` or `sda1`.
+With secure boot in place, TPM can be used to automatically unlock encrypted partitions. After enabling this feature in the BIOS, setup your partitions. For each encrypted partition, setup disk unlock by replacing `<encrypted-partion>` with its identifier, e.g. `nvme0n1p1`, `sda1` or `disk/by-label/NIXOS`.
 
 <Tabs syncKey="nix-environment">
 <TabItem label="NixOS">
@@ -61,6 +66,77 @@ sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=0+2+7+12 /dev/<encrypted
 </TabItem>
 </Tabs>
 
+## Troubleshooting
+
+### Outdated secure boot keys
+
+After an OS update while using secure boot, keys might become outdated and this error appears on boot:
+
+```
+Verification failed: (0x1A) Security Violation
+```
+
+The following steps might resolve this issue.
+
+<Steps>
+<ol>
+<li>
+
+Disable secure boot in the UEFI.
+
+</li>
+<li>
+
+Reset the keys.
+
+<Tabs syncKey="nix-environment">
+<TabItem label="NixOS">
+
+```sh
+sudo nix run nixpkgs#sbctl reset
+```
+
+</TabItem>
+</Tabs>
+
+</li>
+<li>
+
+[Setup secure boot](#setup) again.
+
+</li>
+</ol>
+</Steps>
+
+### Outdated TPM disk unlock
+
+After an OS or UEFI update using TPM disk unlock, the disks may not be automatically unlocked and you will be prompted for the encryption password on boot. The following steps might resolve this issue.
+
+<Steps>
+<ol>
+<li>
+
+For each encrypted partition, remove disk unlock by replacing `<encrypted-partion>` with its identifier, e.g. `nvme0n1p1`, `sda1` or `disk/by-label/NIXOS`.
+
+<Tabs syncKey="nix-environment">
+<TabItem label="NixOS">
+
+```sh
+sudo systemd-cryptenroll --wipe-slot tpm2 /dev/<encrypted-partition>
+```
+
+</TabItem>
+</Tabs>
+
+</li>
+<li>
+
+[Setup TPM disk unlock](#tpm-disk-unlock) again.
+
+</li>
+</ol>
+</Steps>
+
 ## Further reading
 
 - Setting up [lanzaboote](https://github.com/nix-community/lanzaboote/blob/master/docs/QUICK_START.md)