summaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md100
1 files changed, 12 insertions, 88 deletions
diff --git a/README.md b/README.md
index 51aa5b7..a27d499 100644
--- a/README.md
+++ b/README.md
@@ -6,100 +6,24 @@ mkinitcpio-ykfde
This allows to automatically unlock a LUKS encrypted hard disk from `systemd`-
enabled initramfs.
-Requirements
-------------
+Requirements, building, installing and usage
+--------------------------------------------
-To compile and use yubico full disk encryption you need:
+Most of this is generic, but it still differs in detail for
+distributions. Please look at what matches best for you.
-* [yubikey-personalization](https://github.com/Yubico/yubikey-personalization)
-* [iniparser](http://ndevilla.free.fr/iniparser/)
-* [systemd](http://www.freedesktop.org/wiki/Software/systemd/)
-* [cryptsetup](http://code.google.com/p/cryptsetup/)
-* [mkinitcpio](https://projects.archlinux.org/mkinitcpio.git/) (Though
- it may be easy to port this to any initramfs that uses systemd)
-* [markdown](http://daringfireball.net/projects/markdown/) (HTML documentation)
-* [libarchive](http://www.libarchive.org/) (Update challenge on boot)
-
-Additionally it is expected to have `make` and `pkg-config` around to
-successfully compile.
-
-Build and install
------------------
-
-Building and installing is very easy. Just run:
-
-> make
-
-followed by:
-
-> make install
-
-This will place files to their desired places in filesystem.
-
-Usage
------
-
-Make sure systemd knows about your encrypted device by
-adding a line to `/etc/crypttab.initramfs`. It should read like:
-
-> `mapping-name` /dev/`LUKS-device` -
-
-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:
-
- [general]
- device name = crypt
-
- [1234567]
- luks slot = 1
-
-*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
-the key. Plug it in, make sure it is configured for `HMAC-SHA1`.
-After that run:
-
-> ykfde
-
-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`).
-
-### `ykfde` hook
-
-Last add `ykfde` to your hook list in `/etc/mkinitcpio.conf` and rebuild
-your initramfs with:
-
-> mkinitcpio -p linux
-
-Reboot and have fun!
-
-### `ykfde-cpio` hook
-
-Add `ykfde-cpio` to your hook list in `/etc/mkinitcpio.conf` and rebuild
-your initramfs with:
-
-> mkinitcpio -p linux
-
-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).
-
-Reboot and have fun!
+* [mkinitcpio based initramfs (Arch Linux, ...)](README-mkinitcpio.md)
+* [dracut based initramfs (Fedora, ...)](README-dracut.md)
Limitation / TODO
-----------------
-* At the moment this is specific to Arch Linux. Though everything should
- run with upstream `systemd` just fine anybody has to hook things up with
- [dracut](https://dracut.wiki.kernel.org/) or whatever.
+* [systemd password agents](http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents/)
+ do not support nested queries. That is why we can not ask for a
+ password ourselfs, breaking two factor authentication (2FA).
+* When using your additional initramfs `grub-mkconfig` does not know
+ about that. Regenerating `grub` configuration file `grub.cfg` will
+ overwrite our changes.
### Upstream