Add note

remove # in front of relevant settings

CHANGELOG.md

@@ -1 +1,23 @@
 # Changelog
+
+## 2019-01-07
+
+- Add Arch recovery chapter to add or replace an YubiKey
+
+## 2018-12-29
+
+- Add Arch helper scripts
+- Improve Arch guide with more hints
+
+## 2018-12-18
+
+- Add Security chapter
+
+## 2018-09-23
+
+- Add backup note and single YubiKey warning
+
+## 2018-07-24
+
+- Add Arch YubiKey login chapter
+- Add Arch Secure Boot chapter

README.md

@@ -1,7 +1,7 @@
 # YubiKey Full Disk Encryption
 
-[This repository](https://github.com/sandrokeil/yubikey-full-disk-encryption-secure-boot-uefi "YubiKey Full Disk Encryption Repository") 
+[This repository](https://github.com/sandrokeil/yubikey-full-disk-encryption-secure-boot-uefi "YubiKey Full Disk Encryption Repository")
-contains a step-by-step tutorial to create a full disk encryption setup with two factor authentication (2FA) 
+contains a step-by-step tutorial to create a full disk encryption setup with two factor authentication (2FA)
 via [YubiKey](https://yubico.com/products/yubikey-hardware/). It contains:
 
 - YubiKey encrypted `root (/)` and `home (/home)` folder on separated partitions
@@ -11,11 +11,16 @@ via [YubiKey](https://yubico.com/products/yubikey-hardware/). It contains:
 
 Currently guides for:
 
-- Arch Linux 
+- Arch Linux with helper scripts
+
+Additional security chapter:
+
+- Disable INTEL AMT
+- Disable AMD PSP
 
 ## Why
 It took me several days to figure out how to set up a fully encrypted machine with 2FA. This guide should help
-others to get it done in minutes (hopefully). There exists a plenty bunch of tutorials but no one contains a step-by-step 
+others to get it done in minutes (hopefully). There exists a plenty bunch of tutorials but no one contains a step-by-step
 guide to get the above things done.
 
 > I guess the entire manual will take between 1 - 3 hours.
@@ -25,7 +30,7 @@ You should be familiar with linux and should be able to edit files with `vi` [Vi
 You need an USB stick for the Linux Live environment and a second computer would be useful for look ups and to read this guide while
 preparing your fully encrypted Linux.
 
-And of course you will need at least **two** [YubiKeys](https://www.yubico.com/products/yubikey-hardware/ "Discover YubiKeys").  
+And of course you will need at least **two** [YubiKeys](https://www.yubico.com/products/yubikey-hardware/ "Discover YubiKeys").
 
 **WARNING:** You gonna get a bricked machine if you only have a single Yubikey and it breaks.
 
@@ -38,7 +43,7 @@ And of course you will need at least **two** [YubiKeys](https://www.yubico.com/p
 ## Documentation
 
 For the latest online documentation visit [http://sandrokeil.github.io/yubikey-full-disk-encryption-secure-boot-uefi/](http://sandrokeil.github.io/yubikey-full-disk-encryption-secure-boot-uefi/ "Latest yubikey-full-disk-encryption-secure-boot-uefi documentation").
-Refer the *Quick Start* section for a detailed explanation. 
+Refer the *Quick Start* section for a detailed explanation.
 
 Documentation is [in the book tree](book/), and can be compiled using [bookdown](http://bookdown.io) or [Docker](https://www.docker.com/)
 

book/arch/01-getting-started.md

@@ -1,7 +1,9 @@
 # Getting Started
 
+> You can use the file `scripts/arch/01-init.sh`
+
 For common stuff, the Arch Wiki is a good starting point. You need a bootable Arch Linux medium. Please take a look
-at the Arch installation guide [en](https://wiki.archlinux.org/index.php/installation_guide#Pre-installation "Download and boot the installation medium") / [de](https://wiki.archlinux.de/title/Anleitung_für_Einsteiger#Das_neueste_ISO-Abbild_beziehen "Das neueste ISO-Abbild beziehen"). 
+at the Arch installation guide [en](https://wiki.archlinux.org/index.php/installation_guide#Pre-installation "Download and boot the installation medium") / [de](https://wiki.archlinux.de/title/Anleitung_für_Einsteiger#Das_neueste_ISO-Abbild_beziehen "Das neueste ISO-Abbild beziehen").
 
 Ok, you've create a bootable Arch Linux medium, now it's time to boot into the Arch Linux UEFI system.
 

book/arch/02-prepare-disk.md

@@ -4,8 +4,8 @@ You have [different choices](https://wiki.archlinux.org/index.php/Dm-crypt/Encry
 This chapter describes [LVM on LUKS with encrypted boot partition](https://wiki.archlinux.org/index.php/Dm-crypt/Encrypting_an_entire_system#Encrypted_boot_partition_.28GRUB.29 "Encrypted boot partition (GRUB)").
 Because we want to unlock all volumes at once.
 
-List your disks with `lsblk` and run `gdisk /dev/[your disk]` e.g. `gdisk /dev/nvme0n1`. You can take a look at the 
+List your disks with `lsblk` and run `gdisk /dev/[your disk]` e.g. `gdisk /dev/nvme0n1`. You can take a look at the
-`gdisk` Arch Wiki [en](https://wiki.archlinux.org/index.php/Fdisk#gdisk) / [de](https://wiki.archlinux.de/title/GPT#Partitionieren_mit_gdisk)
+`gdisk` Arch Wiki [en](https://wiki.archlinux.org/index.php/Gdisk) / [de](https://wiki.archlinux.de/title/GPT#Partitionieren_mit_gdisk)
 
 > It's crucial to use `gdisk` because GPT is needed for UEFI boot.
 
@@ -20,8 +20,8 @@ Number  Start (sector)    End (sector)  Size       Code  Name
    4         2461696      2000409230   952.7 GiB   8E00  Linux LVM
 ```
 
-The second partition contains the EFI System and must be of type FAT32. 
+The second partition contains the EFI System and must be of type FAT32.
-Format the second partition (replace `[device 2nd partition]` with the 2nd partition of your device e.g. `/dev/nvme0n1p2`) with: 
+Format the second partition (replace `[device 2nd partition]` with the 2nd partition of your device e.g. `/dev/nvme0n1p2`) with:
 
 ```
 mkfs.fat -F32 /dev/[device 2nd partition]

book/arch/03-prepare-yubikey.md

@@ -1,5 +1,7 @@
 # Prepare YubiKey
 
+> You can use the file `scripts/arch/03-ykfde.sh`.
+
 Download or mount [yubikey-full-disk-encryption](https://github.com/agherzan/yubikey-full-disk-encryption) and install it
 in your Arch Linux Live environment. This is needed because we will format the 4th partition with YubiKey.
 
@@ -13,26 +15,32 @@ make install
 
 
 ## Prepare 2nd slot
-Now it's time to prepare the second slot of your YubiKey for the [challenge response authentication](https://wiki.archlinux.org/index.php/yubikey#Challenge-Response "Setup YubiKey Challenge-Response"). 
+Now it's time to prepare the second slot of your YubiKey for the [challenge response authentication](https://wiki.archlinux.org/index.php/yubikey#Challenge-Response "Setup YubiKey Challenge-Response").
-Touch will be also enabled. You can also install the package `yubikey-personalization-gui`. It allows for customization of the secret key, 
+Touch will be also enabled. You can also install the package [`yubikey-personalization-gui`](https://www.kryptel.com/articles/yubikey_setup.php). It allows for customization of the secret key,
-creation of secret key backup and writing the same secret key to multiple YubiKeys which allows for using them interchangeably for creating 
+creation of secret key backup and writing the same secret key to multiple YubiKeys which allows for using them interchangeably for creating
 same *ykfde* passphrases.
 
-> Securely save the 20 byte length secret key from the output, so you can use it to initialize another YubiKey as backup.
+> Securely save the 20 byte length secret **key** from the output, so you can use it to initialize another YubiKey as backup.
 
 ```
 ykpersonalize -v -2 -ochal-resp -ochal-hmac -ohmac-lt64 -ochal-btn-trig -oserial-api-visible
 ```
 
+The output contains the secret **key** e.g. `7fb21c407f0693ab30259664680a047f8c462ccb` to replace a faulty YubiKey.
+
 ## Configure ykfde
-Open `/etc/ykfde.conf` and set `YKFDE_CHALLENGE_SLOT=2` because we want to use the second slot. 
+Open `/etc/ykfde.conf` and set `YKFDE_CHALLENGE_SLOT=2` because we want to use the second slot.
 Set `YKFDE_CHALLENGE_PASSWORD_NEEDED=1` so it asks for the password (2FA). Leave other settings as is, it will be changed
 later.
 
-> Please compare it carefully with the latest version you have downloaded. 
+> Please compare it carefully with the latest version you have downloaded.
+
+It should look something like this
 
 ```ini
-# Configuration for yubikey-full-disk-encryption. ("") means an empty value.
+### Configuration for 'yubikey-full-disk-encryption'.
+### Remove hash (#) symbol and set non-empty ("") value for chosen options to
+### enable them.
 
 ### *REQUIRED* ###
 
@@ -42,41 +50,55 @@ later.
 # Use 'Manual mode with secret challenge (2FA)'.
 YKFDE_CHALLENGE_PASSWORD_NEEDED="1"
 
-# Choose YubiKey slot configured for 'HMAC-SHA1 Challenge-Response' mode. Possible values are "1" or "2".
+# YubiKey slot configured for 'HMAC-SHA1 Challenge-Response' mode.
+# Possible values are "1" or "2". Defaults to "2".
 YKFDE_CHALLENGE_SLOT="2"
 
 ### OPTIONAL ###
 
-# Set partition UUID. Leave empty to use 'cryptdevice' kernel parameter.
+# UUID of device to unlock with 'cryptsetup'.
+# Leave empty to use 'cryptdevice' boot parameter.
 #YKFDE_DISK_UUID=""
 
-# Set LUKS encrypted volume name. Leave empty to use 'cryptdevice' kernel parameter.
+# LUKS encrypted volume name after unlocking.
+# Leave empty to use 'cryptdevice' boot parameter.
 #YKFDE_LUKS_NAME=""
 
-# If left empty this will be set as "/dev/disk/by-uuid/$YKFDE_DISK_UUID" -- device to unlock with 'cryptsetup luksOpen'.
+# Device to unlock with 'cryptsetup'. If left empty and 'YKFDE_DISK_UUID'
+# is enabled this will be set as "/dev/disk/by-uuid/$YKFDE_DISK_UUID".
+# Leave empty to use 'cryptdevice' boot parameter.
 #YKFDE_LUKS_DEV=""
 
-# Optional flags passed to 'cryptsetup luksOpen'. Example: "--allow-discards" for TRIM support. Leave empty to use cryptdevice kernel parameter.
+# Optional flags passed to 'cryptsetup'. Example: "--allow-discards" for TRIM
+# support. Leave empty to use 'cryptdevice' boot parameter.
 #YKFDE_LUKS_OPTIONS=""
 
-# Number of times to assemble passphrase and run 'cryptsetup luksOpen'. Defaults to "5".
+# Number of times to try assemble 'ykfde passphrase' and run 'cryptsetup'.
+# Defaults to "5".
 #YKFDE_CRYPTSETUP_TRIALS="5"
 
-# Number of seconds to wait for inserting YubiKey, "-1" means 'unlimited'. Defaults to "30".
+# Number of seconds to wait for inserting YubiKey, "-1" means 'unlimited'.
+# Defaults to "30".
 #YKFDE_CHALLENGE_YUBIKEY_INSERT_TIMEOUT="30"
 
-# Number of seconds passed to 'sleep' after succesful decryption. Defaults to empty, meaning NO sleep.
+# Number of seconds to wait after successful decryption.
+# Defaults to empty, meaning NO wait.
 #YKFDE_SLEEP_AFTER_SUCCESSFUL_CRYPTSETUP=""
 
-# Enable verbose output. It will print all secrets to terminal. Use only for debugging.
+# Verbose output. It will print all secrets to terminal.
+# Use only for debugging.
 #DBG="1"
 ```
 
 ## Encrypt 4th partition
-Next step is to format the 4th partition. You can modify the arguments if you know what you are doing. 
+Next step is to format the 4th partition. You can modify the arguments if you know what you are doing.
 
 > Ensure that you use the 4th partition, replace `[device 4th partition]` with the 4th partition of your device e.g. `nvme0n1p4`
 
+The command `ykfde-format` will prompt to enter your challenge (2FA) password. Use a strong password which you can remember.
+You have to type this password every time to get access via YubiKey and to decrypt your disk. The command `ykfde-open`
+will unlock a LUKS encrypted volume on a running system.
+
 ```
 ykfde-format --cipher aes-xts-plain64 --key-size 512 --hash sha256 --iter-time 5000 --type luks2 /dev/[device 4th partition]
 ykfde-open -d /dev/[device 4th partition] -n cryptlvm

book/arch/04-prepare-volumes.md

@@ -1,5 +1,7 @@
 # Prepare Volumes
 
+> You can use the file `scripts/arch/04-prepare-volumes.sh`
+
 Please take a look at the Arch Wiki page [Preparing the logical volumes](https://wiki.archlinux.org/index.php/Dm-crypt/Encrypting_an_entire_system#Preparing_the_logical_volumes "preparing the logical volumes")
 to create `/` and `/home` directory/partitions. In short you do this (without swap).
 
@@ -9,7 +11,7 @@ to create `/` and `/home` directory/partitions. In short you do this (without sw
 pvcreate /dev/mapper/cryptlvm
 vgcreate MyVolGroup /dev/mapper/cryptlvm
 
-lvcreate -L 30G MyVolGroup -n root
+lvcreate -L 20G MyVolGroup -n root
 lvcreate -l 100%FREE MyVolGroup -n home
 
 mkfs.ext4 /dev/MyVolGroup/root
@@ -26,13 +28,16 @@ The last volume is `/boot` which should also be encrypted. You can not use a Yub
 The Arch Wiki page [Preparing the boot partition](https://wiki.archlinux.org/index.php/Dm-crypt/Encrypting_an_entire_system#Preparing_the_boot_partition_5 "Preparing the boot partition")
 describes this in more detail. The `efi` partition will be mounted to `/boot/efi`.
 
-> Be aware, GRUB boot loader uses US keyboard layout. Consider this for your password!
-
 Execute the following commands and replace `[device 3rd partition]` with the 3rd partition of your device e.g. `nvme0n1p3`
 and replace `[device 2nd partition]` with the 2nd partition of your device e.g. `nvme0n1p2`.
 
+The command `cryptsetup luksFormat` will prompt to enter your password to decrypt the boot partition at boot.
+Use a strong password which you can remember.
+
+> Be aware, GRUB boot loader uses US keyboard layout. German users should execute `loadkeys us` before running `cryptsetup` commands.
+
 ```
-cryptsetup luksFormat /dev/[device 3rd partition]
+cryptsetup luksFormat --type luks1 /dev/[device 3rd partition]
 cryptsetup open /dev/[device 3rd partition] cryptboot
 
 ls /dev/mapper
@@ -57,4 +62,6 @@ The keyfile is copied in the root folder of the new Arch linux environment.
 dd bs=512 count=4 if=/dev/urandom of=/mnt/crypto_keyfile.bin
 chmod 000 /mnt/crypto_keyfile.bin
 cryptsetup luksAddKey /dev/[device 3rd partition] /mnt/crypto_keyfile.bin
-```
+```
+
+Now it's time to install Arch. You have made a great progress!

book/arch/05-install-arch.md

@@ -1,5 +1,7 @@
 # Install Arch Linux
 
+> You can use the file `scripts/arch/05-install.sh`.
+
 This chapter describes how to install a minimal Arch Linux. You will find an appropriated page in the Arch Wiki
 [en](https://wiki.archlinux.org/index.php/installation_guide) / [de](https://wiki.archlinux.de/title/Anleitung_f%C3%BCr_Einsteiger).
 
@@ -28,10 +30,10 @@ available inside the new system. More on that later. Replace `[Your YubiKey pass
 
 ```
 cp -r yubikey-full-disk-encryption /mnt/home/
-echo "export YKFDE_CHALLENGE=$(printf [Your YubiKey password] | sha256sum | awk '{print $1}')" > /mnt/home/challenge.txt
+echo "export YKFDE_CHALLENGE=$(printf '[Your YubiKey password]' | sha256sum | awk '{print $1}')" > /mnt/home/challenge.txt
 ```
 
-Copy `/etc/ykde.conf` to `/mnt/home` so you can use this file later in your new environment.  
+Copy `/etc/ykfde.conf` to `/mnt/home` so you can use this file later in your new environment.
 
 ## Mount run folder
 
@@ -46,9 +48,17 @@ mount --bind /run /mnt/hostrun
 
 ## chroot
 
+> You can use the file `scripts/arch/05-chroot.sh`.
+
 It's time to switch into your new system with `arch-chroot /mnt` and prepare some stuff. After successfully changed root to
 the new system, execute the following lines to make the hosts *lvm* available here for `grub-mkconfig`.
 
+You will need the same packages like in chapter *01: Getting Started*.
+
+```
+pacman -Sy yubikey-manager yubikey-personalization pcsc-tools libu2f-host make json-c cryptsetup
+```
+
 ```
 mkdir /run/lvm
 mount --bind /hostrun/lvm /run/lvm
@@ -62,20 +72,20 @@ cd /home/yubikey-full-disk-encryption
 make install
 ```
 
-Copy `/home/ykde.conf` to  `/etc/ykde.conf` so you have your previous settings or configure the file as described 
+Copy `/home/ykfde.conf` to  `/etc/ykfde.conf` so you have your previous settings or configure the file as described
-in chapter *Prepare YubiKey*. The YubiKey challenge will now be stored in the `ykde.conf` 
+in chapter *Prepare YubiKey*. The YubiKey challenge will now be stored in the `ykfde.conf`
-file. The environment variable with the YubiKey challenge is loaded into the environment so it can be set 
+file. The environment variable with the YubiKey challenge is loaded into the environment so it can be set
-into the `ykde.conf` file with the command `sed`.
+into the `ykfde.conf` file with the command `sed`.
 
 ```
 source /home/challenge.txt
-sed -i "s/#YKFDE_CHALLENGE=/YKFDE_CHALLENGE=$YKFDE_CHALLENGE/g" /etc/ykde.conf
+sed -i "s/#YKFDE_CHALLENGE=\"/YKFDE_CHALLENGE=\"$YKFDE_CHALLENGE/g" /etc/ykfde.conf
 ```
 
-Check that the YubiKey challenge was successfully saved to `/etc/ykde.conf` with `cat /etc/ykde.conf`.
+Check that the YubiKey challenge was successfully saved to `/etc/ykfde.conf` with `cat /etc/ykfde.conf`.
 
 ## mkinitcpio
-The next step is to prepare the `mkinitcpio.conf` to detect and unlock an encrypted partition at boot. Open the file with 
+The next step is to prepare the `mkinitcpio.conf` to detect and unlock an encrypted partition at boot. Open the file with
 `vi /etc/mkinitcpio.conf` and replace the *HOOKS* line with the following content.
 
 > Don't add `encrypt` hook, because we ues ykfde and respect the order !!!
@@ -90,24 +100,32 @@ Additionally the *ext4* module is needed. Add *ext4* to the *MODULES*. It should
 MODULES=(ext4)
 ```
 
+### German users
+German users have to configure german keyboard layout, otherwise YubiKey passphrase will be wrong.
+
+```
+echo KEYMAP=de-latin1 > /etc/vconsole.conf
+echo FONT=lat9w-16 >> /etc/vconsole.conf
+```
+
 ## GRUB
 The next part is a bit tricky, because you have to figure out the correct device UUIDs. First, get a list of your device
-IDs with `lsblk -f` it should look something like this:
+IDs with `lsblk -f`. Alternative `blkid` can be used. It should look something like this:
 
 ```
 NAME                  FSTYPE      LABEL UUID                                   MOUNTPOINT
-nvme0n1                                                                        
+nvme0n1
-├─nvme0n1p1                                                                    
+├─nvme0n1p1
 ├─nvme0n1p2           vfat              AB24-1550                              /boot/efi
-├─nvme0n1p3           crypto_LUKS       434a512a-1b76-449e-8cb0-f93aee46e85c   
+├─nvme0n1p3           crypto_LUKS       434a512a-1b76-449e-8cb0-f93aee46e85c
 │ └─cryptboot         ext4              5fe2b9c5-ac2b-4f6e-8f3e-5e45c45d0b02   /boot
-└─nvme0n1p4           crypto_LUKS       a86c6534-6643-4afa-b3ae-c78a0a5dc50f   
+└─nvme0n1p4           crypto_LUKS       a86c6534-6643-4afa-b3ae-c78a0a5dc50f
-  └─cryptlvm          LVM2_member       heTIE6-0pLH-8J8Y-67T7-1vPW-4f1V-SqHeOA 
+  └─cryptlvm          LVM2_member       heTIE6-0pLH-8J8Y-67T7-1vPW-4f1V-SqHeOA
     ├─MyVolGroup-root ext4              49a833a2-4a3b-4a1b-a7d9-75ab50910a8e   /
     └─MyVolGroup-home ext4              ec626537-c6a5-4df9-9ad9-3a344bc8c86f   /home
 ```
 
-You will need the UUID from the *device 4th partition* (in this example *a86c6534-6643-4afa-b3ae-c78a0a5dc50f*) and the 
+You will need the UUID from the *device 4th partition* (in this example *a86c6534-6643-4afa-b3ae-c78a0a5dc50f*) and the
 UUID of *MyVolGroup-root* (in this example *49a833a2-4a3b-4a1b-a7d9-75ab50910a8e*). Open the GRUB config file with `vi /etc/default/grub`
 and add these two lines with your UUIDs.
 
@@ -145,14 +163,16 @@ It should look like this with your UUID of the 3rd partition.
 cryptboot      UUID=434a512a-1b76-449e-8cb0-f93aee46e85c    /crypto_keyfile.bin                    luks
 ```
 
-## Configure ykde.conf
+## Configure ykfde.conf
-Open the file with `vi /etc/ykde.conf` and enable/set `YKFDE_LUKS_NAME="cryptlvm"` and  `YKFDE_DISK_UUID=[4th partition UUID]` 
+Open the file with `vi /etc/ykfde.conf` and enable/set `YKFDE_LUKS_NAME="cryptlvm"` and  `YKFDE_DISK_UUID=[4th partition UUID]`
 (replace `[4th partition UUID]` with the UUID of the 4th partition e.g. `a86c6534-6643-4afa-b3ae-c78a0a5dc50f`).
 Feel free to modify it to your needs e.g. enable TRIM (but be warned, there are potential security implications) support.
 It should look something like this
 
 ```ini
-# Configuration for yubikey-full-disk-encryption. ("") means an empty value.
+### Configuration for 'yubikey-full-disk-encryption'.
+### Remove hash (#) symbol and set non-empty ("") value for chosen options to
+### enable them.
 
 ### *REQUIRED* ###
 
@@ -162,43 +182,53 @@ YKFDE_CHALLENGE="8fa0acf6233b92d2d48a30a315cd213748d48f28eaa63d7590509392316b301
 # Use 'Manual mode with secret challenge (2FA)'.
 YKFDE_CHALLENGE_PASSWORD_NEEDED="1"
 
-# Choose YubiKey slot configured for 'HMAC-SHA1 Challenge-Response' mode. Possible values are "1" or "2".
+# YubiKey slot configured for 'HMAC-SHA1 Challenge-Response' mode.
+# Possible values are "1" or "2". Defaults to "2".
 YKFDE_CHALLENGE_SLOT="2"
 
 ### OPTIONAL ###
 
-# Set partition UUID. Leave empty to use 'cryptdevice' kernel parameter.
+# UUID of device to unlock with 'cryptsetup'.
+# Leave empty to use 'cryptdevice' boot parameter.
 YKFDE_DISK_UUID="a86c6534-6643-4afa-b3ae-c78a0a5dc50f"
 
-# Set LUKS encrypted volume name. Leave empty to use 'cryptdevice' kernel parameter.
+# LUKS encrypted volume name after unlocking.
+# Leave empty to use 'cryptdevice' boot parameter.
 YKFDE_LUKS_NAME="cryptlvm"
 
-# If left empty this will be set as "/dev/disk/by-uuid/$YKFDE_DISK_UUID" -- device to unlock with 'cryptsetup luksOpen'.
+# Device to unlock with 'cryptsetup'. If left empty and 'YKFDE_DISK_UUID'
+# is enabled this will be set as "/dev/disk/by-uuid/$YKFDE_DISK_UUID".
+# Leave empty to use 'cryptdevice' boot parameter.
 #YKFDE_LUKS_DEV=""
 
-# Optional flags passed to 'cryptsetup luksOpen'. Example: "--allow-discards" for TRIM support. Leave empty to use cryptdevice kernel parameter.
+# Optional flags passed to 'cryptsetup'. Example: "--allow-discards" for TRIM
+# support. Leave empty to use 'cryptdevice' boot parameter.
 #YKFDE_LUKS_OPTIONS=""
 
-# Number of times to assemble passphrase and run 'cryptsetup luksOpen'. Defaults to "5".
+# Number of times to try assemble 'ykfde passphrase' and run 'cryptsetup'.
+# Defaults to "5".
 #YKFDE_CRYPTSETUP_TRIALS="5"
 
-# Number of seconds to wait for inserting YubiKey, "-1" means 'unlimited'. Defaults to "30".
+# Number of seconds to wait for inserting YubiKey, "-1" means 'unlimited'.
+# Defaults to "30".
 #YKFDE_CHALLENGE_YUBIKEY_INSERT_TIMEOUT="30"
 
-# Number of seconds passed to 'sleep' after succesful decryption. Defaults to empty, meaning NO sleep.
+# Number of seconds to wait after successful decryption.
+# Defaults to empty, meaning NO wait.
 #YKFDE_SLEEP_AFTER_SUCCESSFUL_CRYPTSETUP=""
 
-# Enable verbose output. It will print all secrets to terminal. Use only for debugging.
+# Verbose output. It will print all secrets to terminal.
+# Use only for debugging.
 #DBG="1"
 ```
 
 ## Test it
-It's time to check you settings with a graceful reboot. If you have done all things right you will be asked for your 
+It's time to check your settings with a graceful reboot. If you have done all things right, you will be asked for your
-boot parition password to see the GRUB boot menu and after that the YubiKey password with YubiKey touch button to unlock 
+boot partition password to see the GRUB boot menu and after that, the YubiKey password with YubiKey touch button to unlock
-the root partition. 
+the root partition.
 
-Good luck! Don't worry if something doesn't work, simply boot from the Arch Linux medium, install the necessary software 
+Good luck! Don't worry if something doesn't work, simply boot from the Arch Linux medium, install the necessary software
 to mount your encrypted partitions and check the configs. Maybe an UUID is wrong.
 
 Now you can setup your Arch Linux e.g. create own user or add additional stuff [en](https://wiki.archlinux.org/index.php/installation_guide) / [de](https://wiki.archlinux.de/title/Anleitung_f%C3%BCr_Einsteiger).
-The next chapter describes how to setup UEFI secure boot. The last piece to bullet proof your full disk encryption.
+The next chapter describes how to setup UEFI secure boot. The last piece to bullet proof your full disk encryption.

book/arch/06-secure-boot.md

@@ -1,6 +1,8 @@
 # Setup secure boot
 
-This chapter describes how to configure secure boot because no one should modify the bootloader or boot from another medium. 
+> You can use the file `scripts/arch/06-secure-boot.sh`.
+
+This chapter describes how to configure secure boot because no one should modify the bootloader or boot from another medium.
 Gerke Max Preussner describes this very detailed in his post [Fully Encrypted ArchLinux with Secure Boot on Yoga 920](https://gmpreussner.com/reference/fully-encrypted-archlinux-with-secure-boot-on-yoga-920?#secureboot)
 Please read his chapter about secure boot and come back to enable it.
 
@@ -57,7 +59,7 @@ Exec = /usr/bin/cryptboot update-grub
 
 ## Enable UEFI secure boot
 If you encountered no errors you can now enable UEFI secure boot. Restart the computer and enter BIOS setup.
-                                                                  
+
 1. Navigate to the **Security** page
 1. Go to **Secure Boot** and enable it
 1. Save the changes and exit BIOS Setup

book/arch/07-yubikey-login.md

@@ -15,6 +15,8 @@ sudo pacman -S yubico-pam
 
 Next step is to set the current user to require the YubiKey for logon with the following commands:
 
+> You have to do this for each YubiKey due initial challenge. Remember to touch the device if necessary.
+
 ```
 mkdir $HOME/.yubico
 ykpamcfg -2 -v
@@ -50,7 +52,7 @@ The complete file should look something like this.
 #%PAM-1.0
 
 auth      required  pam_unix.so     try_first_pass nullok
-auth      required  pam_yubico.so   mode=challenge-response chalresp_path=/var/yubico 
+auth      required  pam_yubico.so   mode=challenge-response chalresp_path=/var/yubico
 auth      optional  pam_permit.so
 auth      required  pam_env.so
 
@@ -67,11 +69,11 @@ session   optional  pam_permit.so
 ```
 
 ## Test it
-Arch Linux loads the [PAM](https://wiki.archlinux.org/index.php/PAM "Linux Pluggable Authentication Modules (PAM) ") config files on every login. So simply switch to 
+Arch Linux loads the [PAM](https://wiki.archlinux.org/index.php/PAM "Linux Pluggable Authentication Modules (PAM) ") config files on every login. So simply switch to
 another tty and try to login. After you have entered your password, the YubiKey should flash and you have to touch the
 YubiKey button. Good luck!
 
-**Congratulations**! You have hopefully successful finished the YubiKey Full Disk Encryption Guide. You have reached the 
+**Congratulations**! You have hopefully successful finished the YubiKey Full Disk Encryption Guide. You have reached the
 following goals which is really awesome!
 
 - YubiKey encrypted `root (/)` and `home (/home)` folder on separated partitions
@@ -80,4 +82,6 @@ following goals which is really awesome!
 - YubiKey authentication for user login
 
 If you have any suggestions don't hesitate to [create an issue](https://github.com/sandrokeil/yubikey-full-disk-encryption-secure-boot-uefi/issues "Create a new issue") to improve this guide.
-Also spread the word about this guide so more people can secure their system.
+Also spread the word about this guide so more people can secure their system.
+
+You should now check the *security* chapter to improve security further.

book/arch/bookdown.json

@@ -7,7 +7,8 @@
         {"prepare-volumes": "04-prepare-volumes.md"},
         {"install-arch": "05-install-arch.md"},
         {"secure-boot": "06-secure-boot.md"},
-        {"yubikey-login": "07-yubikey-login.md"}
+        {"yubikey-login": "07-yubikey-login.md"},
+        {"yubikey-recovery": "recovery/bookdown.json"}
     ],
     "theme": {
         "toc": {

book/arch/recovery/add-or-replace-luks-yubikey.md

@@ -0,0 +1,50 @@
+# Add or Replace LUKS YubiKey
+
+> Create a reliable backup of your files!
+
+This chapter describes how to add a new YubiKey or replace an YubiKey for an already encrypted LUKS volume.
+
+You need these things:
+- Your current (old) YubiKey
+- Your new Yubikey
+- Make sure YubiKey login is disabled
+
+> This is only needed if you don't have the secret key of your current YubiKey
+and if you want to replace it with another YubiKey or to add a second different YubiKey.
+See *Replace a faulty YubiKey* if you want to initialize a new YubiKey with the secret key.
+
+> If you are changing the passphrase of your new YubiKey, don't forget to update the *YKFDE_CHALLENGE* in `/etc/ykfde.conf`
+
+Prepare your new YubiKey like described in chapter *03: Prepare 2nd slot* if not already done.
+
+Display current used LUKS key slots with `cryptsetup luksDump /dev/[device 4th partition]`.
+
+## Disable YubiKey login
+
+If you use YubiKey login, disable it and reread chapter *07: Enable YubiKey Login* after this procedure.
+To disable YubiKey login open the file `/etc/pam.d/system-auth` and comment out the line:
+
+```
+auth   required        pam_yubico.so mode=challenge-response chalresp_path=/var/yubico
+```
+
+Use another tty to test it.
+
+## Add an YubiKey to LUKS
+
+Execute `ykfde-enroll -d /dev/[device 4th partition] -s [keyslot_number] -o`. The option `-o` uses the old YubiKey
+for the passphrase. Ensure your new YubiKey is inserted, you will be asked to insert the old YubiKey.
+
+## Killing a LUKS key slot
+
+> Ensure you are not killing a wrong key slot and make sure another key slot is working.
+
+To test which YubiKey belongs to which key slot execute `ykfde-open -d /dev/[device 4th partition] -s [keyslot_number] -t`.
+
+Execute `ykfde-enroll -d /dev/[device 4th partition] -s [keyslot_number] -k`.  The option `-k` kills the slot.
+
+## Replacing existing LUKS key slot
+
+> It is recommended to add a new YubiKey to another slot and kill the other slot if all things work.
+
+Execute `ykfde-enroll -d /dev/[device 4th partition] -s [keyslot_number] -o -c `. The option `-c` changes the key slot.

book/arch/recovery/bookdown.json

@@ -0,0 +1,22 @@
+{
+    "title": "YubiKey Recovery",
+    "content": [
+        {"replace-faulty-yubikey": "replace-faulty-yubikey.md"},
+        {"add-or-replace-luks-yubikey": "add-or-replace-luks-yubikey.md"}
+    ],
+    "theme": {
+        "toc": {
+            "collapsibleFromLevel": 1
+        }
+    },
+    "template": "bookdown/themes",
+    "tocDepth": 2,
+    "target": "../html",
+    "numbering": false,
+    "extensions": {
+        "commonmark": [
+            "Webuni\\CommonMark\\TableExtension\\TableExtension",
+            "Webuni\\CommonMark\\AttributesExtension\\AttributesExtension"
+        ]
+    }
+}

book/arch/recovery/replace-faulty-yubikey.md

@@ -0,0 +1,20 @@
+# Replace a faulty YubiKey
+
+> You will need the 20 byte length secret key from the initialization.
+
+The secret key in the example here is *7fb21c407f0693ab30259664680a047f8c462ccb*.
+
+```
+LOGGING START,3/9/2018 5:00 PM
+Challenge-Response: HMAC-SHA1,3/9/2018 5:00 PM,2,,,7fb21c407f0693ab30259664680a047f8c462ccb,,,0,0,0,0,0,0,0,0,0,0
+```
+
+Repalce `[Your secret key]` with your secret key from initialization.
+
+```
+ykpersonalize -a[your secret key] -v -2 -ochal-resp -ochal-hmac -ohmac-lt64 -ochal-btn-trig -oserial-api-visible
+```
+
+That's it, this YubiKey should work like the others.
+
+> If you use YubiKey Login you have to reread chapter *07: Enable YubiKey Login* due initial challenge.

book/security/bookdown.json

@@ -0,0 +1,22 @@
+{
+    "title": "Security",
+    "content": [
+        {"disable-intel-amt": "disable-intel-amt.md"},
+        {"disable-amd-psp": "disable-amd-psp.md"}
+    ],
+    "theme": {
+        "toc": {
+            "collapsibleFromLevel": 1
+        }
+    },
+    "template": "bookdown/themes",
+    "tocDepth": 2,
+    "target": "../html",
+    "numbering": false,
+    "extensions": {
+        "commonmark": [
+            "Webuni\\CommonMark\\TableExtension\\TableExtension",
+            "Webuni\\CommonMark\\AttributesExtension\\AttributesExtension"
+        ]
+    }
+}

book/security/disable-amd-psp.md

@@ -0,0 +1,13 @@
+# Disable AMD PSP
+This page describes how to disable AMD Secure Processor aka AMD Secure Technology.
+Please read the whole page before you begin. The AMD PSP is a
+[security risk](https://www.scmagazineuk.com/security-issue-found-amds-platform-security-processor/article/1473518 "Security issue found in AMD's Platform Security Processor").
+
+> Don't forget to set a secure BIOS supervisor password!
+
+## Disable AMD PSP in BIOS
+> **Attention:** If you don't see any option to disable AMD PSP, check
+if you have installed the latest BIOS version.
+
+Boot into BIOS and search for an entry *BIOS PSP Support* and disable it.
+It should be in menu *Advanced*.

book/security/disable-intel-amt.md

@@ -0,0 +1,35 @@
+# Disable INTEL AMT
+This page describes how to disable INTEL Active Management Technology. Please read the whole page before you begin.
+The INTEL AMT is a [security risk](https://thehackernews.com/2018/01/intel-amt-vulnerability.html "INTEL AMT vulnerabilities").
+
+> Don't forget to set a secure BIOS supervisor password!
+
+## Open INTEL AMT
+To open INTEL AMT press *CTRL + P* on boot. The default password is *admin* and
+you should change it to a secure one. You will be ask to change the password
+on the first login.
+
+## Disable Intel Management Engine State Control
+Next step is to [Disable Intel Management Engine State Control](https://www.dell.com/support/article/de/de/debsdt1/sln295179/disable-intel-amt-intel-management-engine-state-control?lang=en).
+
+1. Choose *Intel ME General Settings* from menu
+1. Choose *Intel ME State Control* from menu
+1. Choose *Disable*
+1. Choose *Previous* from menu
+
+The machine will reboot now. You can still access INTEL AMT but if you
+enable it again it should use your password and not the default one.
+
+## Disable INTEL AMT in BIOS
+> **Attention:** Depending on the used INTEL AMT version you **can not**
+disable the Intel Management Engine State Control because then the password will be reset. If you don't
+see any entry to disable INTEL AMT, check if you have installed the latest BIOS version.
+
+Boot into BIOS and search for the *Intel AMT* entry and enter it.
+For Lenovo notebooks it's under the menu *Config*. Choose *Disable* and save BIOS settings.
+
+## Validate password protection
+Now it's time to check, if the password is reset if you enable it again. Go into BIOS and enable
+INTEL AMT, save changes and open INTEL AMT with *CTRL + P*. Enable it again, the machine will reboot.
+Go into INTEL AMT with *CTRL + P* and now you should not be able to login with password *admin*.
+Now start from scratch and disable it again.

bookdown.json

@@ -3,11 +3,12 @@
     "content": [
         {"intro": "README.md"},
         {"changelog": "CHANGELOG.md"},
-        {"guides": "book/guides/bookdown.json"}
+        {"guides": "book/guides/bookdown.json"},
+        {"security": "book/security/bookdown.json"}
     ],
     "theme": {
         "toc": {
-            "collapsibleFromLevel": 1
+            "collapsibleFromLevel": 2
         }
     },
     "template": "bookdown/themes",

composer.json

@@ -7,7 +7,7 @@
     "authors": [
         {
             "name": "Sandro Keil",
-            "email": "social@sandro-keil.de",
+            "email": "github@sandro-keil.de",
             "homepage": "https://sandro-keil.de"
         }
     ],
@@ -19,7 +19,10 @@
         "uefi",
         "arch-linux",
         "luks",
-        "lvm2"
+        "lvm2",
+        "security",
+        "intel amt",
+        "amd psp"
     ],
     "require": {
         "bookdown/bookdown": "^1.1.0",

scripts/arch/01-init.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -e
+
+SCRIPT_NAME=`basename "$0"`
+echo "=========== ${SCRIPT_NAME} ==========="
+pacman -Sy yubikey-manager yubikey-personalization pcsc-tools libu2f-host make json-c cryptsetup
+
+systemctl start pcscd.service
+
+ykman list
+
+lsblk
+
+echo ""
+echo "====================="
+echo "Proceed with chapter 02: Prepare disks"

scripts/arch/03-ykfde.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -e
+
+SCRIPT_NAME=`basename "$0"`
+echo "=========== ${SCRIPT_NAME} ==========="
+
+curl -L https://github.com/agherzan/yubikey-full-disk-encryption/archive/master.zip | bsdtar -xvf - -C .
+cd yubikey-full-disk-encryption-master
+make install
+
+echo ""
+echo "====================="
+echo "Proceed with chapter 03: Prepare 2nd slot"

scripts/arch/04-prepare-volumes.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -e
+
+SCRIPT_NAME=`basename "$0"`
+echo "=========== ${SCRIPT_NAME} ==========="
+
+pvcreate /dev/mapper/cryptlvm
+vgcreate MyVolGroup /dev/mapper/cryptlvm
+
+lvcreate -L 20G MyVolGroup -n root
+lvcreate -l 100%FREE MyVolGroup -n home
+
+mkfs.ext4 /dev/MyVolGroup/root
+mkfs.ext4 /dev/MyVolGroup/home
+
+mount /dev/MyVolGroup/root /mnt
+mkdir /mnt/home
+mount /dev/MyVolGroup/home /mnt/home
+
+echo ""
+echo "====================="
+echo "Proceed with chapter 04: Encrypted boot partition"

scripts/arch/05-chroot.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -e
+
+SCRIPT_NAME=`basename "$0"`
+echo "=========== ${SCRIPT_NAME} ==========="
+
+pacman -Sy yubikey-manager yubikey-personalization pcsc-tools libu2f-host make json-c cryptsetup
+
+mkdir -p /run/lvm
+mount --bind /hostrun/lvm /run/lvm
+
+cd /home/yubikey-full-disk-encryption-master
+make install
+
+cp /home/ykfde.conf /etc/ykfde.conf
+
+source /home/challenge.txt
+sed -i "s/#YKFDE_CHALLENGE=\"/YKFDE_CHALLENGE=\"$YKFDE_CHALLENGE/g" /etc/ykfde.conf
+
+cat /etc/ykfde.conf
+
+echo ""
+echo "====================="
+echo "Proceed with chapter 05: mkinitcpio"

scripts/arch/05-install.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -e
+
+SCRIPT_NAME=`basename "$0"`
+echo "=========== ${SCRIPT_NAME} ==========="
+
+pacstrap /mnt base yubikey-manager yubikey-personalization pcsc-tools libu2f-host acpid dbus grub-efi-x86_64 efibootmgr lvm2
+
+genfstab -U -p /mnt >> /mnt/etc/fstab
+
+cat /mnt/etc/fstab
+
+echo ""
+echo "====================="
+echo "Proceed with chapter 05: YubiKey Full Disk Encryption"

scripts/arch/06-secure-boot.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -e
+
+SCRIPT_NAME=`basename "$0"`
+echo "=========== ${SCRIPT_NAME} ==========="
+
+pacman -Sy binutils fakeroot
+
+curl -L https://github.com/xmikos/cryptboot/archive/master.zip | bsdtar -xvf - -C .
+cd cryptboot-master
+
+makepkg -si --skipchecksums
+
+cryptboot-efikeys create
+cryptboot-efikeys enroll
+cryptboot update-grub
+
+echo ""
+echo "====================="
+echo "Proceed with chapter 06: Pacman hooks"