Add Arch YubiKey recovery chapter

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 2019-01-07
+
+- Add Arch recovery chapter to add or replace an YubiKey
+
 ## 2018-12-29
 
 - Add Arch helper scripts

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

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.

bookdown.json

@@ -8,7 +8,7 @@
     ],
     "theme": {
         "toc": {
-            "collapsibleFromLevel": 1
+            "collapsibleFromLevel": 2
         }
     },
     "template": "bookdown/themes",