Merge pull request #203 from linuxboot/copilot/fix-202

Clarify HOTP/TOTP documentation to address USB Security dongle compatibility confusion

Author: tlaurion

About/FAQ.md

@@ -161,25 +161,31 @@ Unlike [Tails](https://tails.boum.org/), which aims to be a stateless OS that
 leaves no trace on the computer of its  presence, Heads is intended for the
 case where you need to store data and state on the computer.
 
-HOTP vs TOTP
+USB Security dongles and firmware verification in Heads
 ----
 
-HOTP (HMAC-based One-time Password algorithm) generates a password
-using hash-based message authentication codes (HMAC) that can be used only for
-the one authentication attempt.  Uniqueness is based on a counter which is
-incremented each authentication attempt.
+Heads can verify firmware integrity using two methods:
 
-TOTP (Time-based One-time Password algorithm) is an extension of HOTP but
-replaces the counter with time.  Because of latency, both network and human,
-and unsynchronised clocks, the one-time password must validate over a range of
-times between the authenticator and the user. Here, time is
-downsampled into larger durations (e.g., 30 seconds) to allow for validity
-between the parties.
+### HOTP verification (with USB Security dongle)
+**Heads generates HOTP codes** and sends them to your USB Security dongle. The dongle verifies these codes automatically. If verification succeeds, Heads boots normally. If it fails, the dongle's LED shows red and boot is halted.
 
-Secuirty wise, HOTP is more susceptible to brute force attacks without
-throttling or limiting the number of failed attempted while TOTP is susceptible
-to phishing attacks and requires a user to enter the code within a given time
-period.
+**Requirements**: Compatible USB Security dongle (see [Prerequisites compatibility table](/Prerequisites#usb-security-dongles-aka-security-token-aka-smartcard))
+
+**Advantages**: Automatic verification, no manual interaction needed, works without accurate time
+
+### TPMTOTP verification (with smartphone)  
+**Heads generates TOTP codes** displayed on screen. You compare these with codes from your phone's authenticator app. If they match, your firmware is verified as safe.
+
+**Requirements**: 
+- Smartphone with authenticator app
+- **Accurate time synchronization**: Heads system clock must be set to UTC/GMT through Options menu. Phone time is typically synced automatically.
+
+**Note**: Time synchronization is critical - if clocks don't match, codes will differ and verification fails.
+
+### OpenPGP signing (all configurations)
+All Heads configurations use your USB Security dongle's OpenPGP support to store your private key and sign `/boot` contents. This works with any OpenPGP-compatible dongle.
+
+For technical details about HOTP verification, see the [Nitrokey HOTP verification project](https://github.com/Nitrokey/nitrokey-hotp-verification).
 
 coreboot vs Linuxboot
 ----

About/Keys.md

@@ -68,6 +68,8 @@ password based on the current clock time, which the user can compare to the
 value displayed on their phone. A new secret must be generated each time the
 firmware is updated since this will change the PCRs.
 
+**Note**: Heads generates TPMTOTP codes that appear on your screen. You compare these with codes from your phone's authenticator app to verify firmware integrity. This works independently of your USB Security dongle. **Critical requirement**: You must manually set the correct time in Heads through the Options menu (UTC/GMT timezone) - if the time doesn't match your phone, verification will fail.
+
 If an attacker can control this shared secret (such as by directly sending PCR
 values into the TPM), they can install malicious firmware in the SPI flash and
 generate valid TOTP codes.

Installing-and-Configuring/Prerequisites.md

@@ -55,6 +55,14 @@ If *you have an external programmer* and *are techsavvy enough to bring their su
 USB Security Dongles (aka security token aka smartcard)
 ---
 
+**All USB Security dongles used with Heads must support OpenPGP** for storing your private key and signing `/boot` contents.
+
+**HOTP verification is optional** but provides automatic firmware verification at boot. Without HOTP, you'll use TPMTOTP (manual verification with your phone). Most [board configurations](/Prerequisites#supported-devices) are available in both HOTP and non-HOTP variants, though some vendors only support HOTP-enabled configurations.
+
+### USB Security dongle compatibility:
+
+**Compatible dongles** must support the specialized HOTP verification protocol developed by Nitrokey. For technical details about this protocol, see the [Nitrokey HOTP verification project](https://github.com/Nitrokey/nitrokey-hotp-verification).
+
 *NOTE* - Heads does **NOT** support FIDO2 or U2F authentication.  Be careful when
  purchasing to buy a compatible key.
 
@@ -64,13 +72,19 @@ USB Security Dongles (aka security token aka smartcard)
 *NOTE* - The NitroKey 3 comes in three sizes: USB A, A-mini and C. Nk3a mini (USB A-mini) is the one most shipped with novacustom and nitropads.
   - ThinkPads have USB A ports, not C. After that, it's users preferences for the form factor desired. 
 
-|Manufacture|Model line|TOTP|HOTP|
-|--|--|:--:|:--:|
-|Yubico|[YubiKey 5 Series](https://www.yubico.com/products/yubikey-5-overview/)|X||
-|Nitrokey|[Nitrokey Pro 2](https://www.nitrokey.com/products/nitrokeys#comparison)|X|X|
-|Nitrokey|[Nitrokey Storage 2](https://www.nitrokey.com/products/nitrokeys#comparison)|X|X|
-|Nitrokey|[Nitrokey 3](https://www.nitrokey.com/products/nitrokeys#comparison)|X|X|
-|Purism|[Librem Key](https://puri.sm/products/librem-key/)|X|X|
+### Supported USB Security dongles:
+
+|Manufacturer|Model|OpenPGP|HOTP verification|Compatible|
+|--|--|:--:|:--:|:--:|
+|Yubico|[YubiKey 5 Series](https://www.yubico.com/products/yubikey-5-overview/)|✅|❌|OpenPGP only|
+|Nitrokey|[Nitrokey Pro 2](https://www.nitrokey.com/products/nitrokeys#comparison)|✅|✅|Full support|
+|Nitrokey|[Nitrokey Storage 2](https://www.nitrokey.com/products/nitrokeys#comparison)|✅|✅|Full support|
+|Nitrokey|[Nitrokey 3](https://www.nitrokey.com/products/nitrokeys#comparison)|✅|✅|Full support|
+|Purism|[Librem Key](https://puri.sm/products/librem-key/)|✅|✅|Full support|
+
+**Notes**: 
+- **OpenPGP only**: Can be used with non-HOTP board configurations (manual TPMTOTP verification)
+- **Full support**: Can be used with both HOTP and non-HOTP board configurations
 
 *NOTE* - If you prefer not to use USB security dongles or want simplified security procedures, see the [Purism Boot Modes](/PurismBootModes) documentation for information about Basic and Restricted boot modes that provide different security/usability trade-offs.