From bcd51134a89e54d93e1a851680506fb38004a3d2 Mon Sep 17 00:00:00 2001
From: Christian Hesse <mail@eworm.de>
Date: Mon, 18 Jan 2016 21:42:08 +0100
Subject: update README-mkinitcpio

---
 README-mkinitcpio.md | 57 ++++++++++++++++++++++++++++------------------------
 1 file changed, 31 insertions(+), 26 deletions(-)

(limited to 'README-mkinitcpio.md')

diff --git a/README-mkinitcpio.md b/README-mkinitcpio.md
index 8043277..3327cb3 100644
--- a/README-mkinitcpio.md
+++ b/README-mkinitcpio.md
@@ -37,6 +37,8 @@ This will place files to their desired places in filesystem.
 Usage
 -----
 
+## config files `/etc/crypttab.initramfs` and `/etc/ykfde.conf`
+
 Make sure systemd knows about your encrypted device by
 adding a line to `/etc/crypttab.initramfs`. It should read like:
 
@@ -45,7 +47,7 @@ adding a line to `/etc/crypttab.initramfs`. It should read like:
 Update `/etc/ykfde.conf` with correct settings. Add `mapping-name` from
 above to `device name` in the `general` section. Then add a new section
 with your key's decimal serial number containing the key slot setting.
-The file should look like this:
+The minimal file should look like this:
 
     [general]
     device name = crypt
@@ -56,7 +58,10 @@ The file should look like this:
 *Be warned*: Do not remove or overwrite your interactive key! Keep that
 for backup and rescue!
 
-`ykfde` will read its information from these files. Then prepare
+## key setup
+
+`ykfde` will read its information from these files and understands some
+additional options. Run `ykfde --help` for details. Then prepare
 the key. Plug it in, make sure it is configured for `HMAC-SHA1`.
 After that run:
 
@@ -66,43 +71,43 @@ This will store a challenge in `/etc/ykfde.d/` and add a new slot to
 your LUKS device. When `ykfde` asks for a password it requires a valid
 password from available slot.
 
-Now you have two choices. Use *either of both* hooks, depending on whether
-you want to update challenge/response on every boot (`ykfde-cpio`) or
-not (`ykfde`).
+Adding a key with second factor is as easy:
 
-### `ykfde` hook
+> ykfde -s 2nd-factor
 
-Last add `ykfde` to your hook list in `/etc/mkinitcpio.conf` and rebuild
-your initramfs with:
+And updating key and second factor is straight forward:
 
-> mkinitcpio -p linux
+> ykfde -s old-2nd-factor -n new-2nd-factor
 
-Reboot and have fun!
+Make sure to enable second factor in `/etc/ykfde.conf`.
 
-### `ykfde-cpio` hook
+## cpio archive with challenges
 
-Add `ykfde-cpio` to your hook list in `/etc/mkinitcpio.conf` and rebuild
-your initramfs with:
+Every time you update a challenge and/or a second factor run:
 
-> mkinitcpio -p linux
+> ykfde-cpio
 
-Additionally enable `systemd` service `ykfde-cpio.service` and make your
-bootloader load the new `cpio` image `/boot/ykfde-challenges.img` (in
-addition to your usual initramfs).
+This will write a cpio archive `/boot/ykfde-challenges.img` containing
+your current challenges. Enable systemd service `ykfde` to do this
+automatically on every boot:
 
-### Optional `ykfde-2f` hook for second factor
+> systemctl enable ykfde.service
 
-This gives the option to add a second factor for authentication.
-With this you need your Yubikey and an additional passphrase to boot
-your systemd.
+## mkinitcpio hook `ykfde`
 
-Add a second factor with `ykfde`:
-
-> ykfde -s xyz
-
-Add `ykfde-2f` to your hook list in `/etc/mkinitcpio.conf` and rebuild
+Last add `ykfde` to your hook list in `/etc/mkinitcpio.conf` and rebuild
 your initramfs with:
 
 > mkinitcpio -p linux
 
+## boot loader
+
+Update you `grub` configuration by running:
+
+> grub-mkconfig -o /boot/grub/grub.cfg
+
+This will add new boot entry that loads the challenges. With other boot
+loaders make sure to load the cpio archive `/boot/ykfde-challenges.img`
+as additional initramfs.
+
 Reboot and have fun!
-- 
cgit v1.2.3-54-g00ecf