summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGravatar Christian Hesse <mail@eworm.de>2015-01-06 11:26:45 +0100
committerGravatar Christian Hesse <mail@eworm.de>2015-01-06 11:26:45 +0100
commite9810f76dae9471d61d3ca475a762d9d64de08bc (patch)
treeb8b26ce43adcd2dc065c0c13017006e7bf9e55b8
parent8cce6dc19907ba44e29555fa83168619365beb32 (diff)
downloadmkinitcpio-ykfde-e9810f76dae9471d61d3ca475a762d9d64de08bc.tar.gz
mkinitcpio-ykfde-e9810f76dae9471d61d3ca475a762d9d64de08bc.tar.zst
update documentation for mkinitcpio & dracut
-rw-r--r--.gitignore2
-rw-r--r--Makefile28
-rw-r--r--README-dracut.md65
-rw-r--r--README-mkinitcpio.md92
-rw-r--r--README.md100
5 files changed, 191 insertions, 96 deletions
diff --git a/.gitignore b/.gitignore
index f18ac78..7a94410 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,5 @@
config.h
-README.html
bin/ykfde
bin/ykfde-cpio
udev/ykfde
+*.html
diff --git a/Makefile b/Makefile
index b57bb88..afc0bcd 100644
--- a/Makefile
+++ b/Makefile
@@ -3,26 +3,33 @@ INSTALL := install
MD := markdown
RM := rm
CP := cp
+SED := sed
# this is just a fallback in case you do not use git but downloaded
# a release tarball...
VERSION := 0.5.0
-all: bin/ykfde bin/ykfde-cpio udev/ykfde README.html
+all: bin/ykfde bin/ykfde-cpio udev/ykfde README.html README-mkinitcpio.html README-dracut.html
bin/ykfde: bin/ykfde.c config.h
- $(MAKE) -C bin
+ $(MAKE) -C bin ykfde
bin/ykfde-cpio: bin/ykfde-cpio.c config.h
- $(MAKE) -C bin
+ $(MAKE) -C bin ykfde-cpio
udev/ykfde: udev/ykfde.c config.h
- $(MAKE) -C udev
+ $(MAKE) -C udev ykfde
config.h: config.def.h
$(CP) config.def.h config.h
README.html: README.md
- $(MD) README.md > README.html
+ $(MD) README.md | $(SED) 's/\(README[-[:alnum:]]*\).md/\1.html/g' > README.html
+
+README-mkinitcpio.html: README-mkinitcpio.md
+ $(MD) README-mkinitcpio.md | $(SED) 's/\(README[-[:alnum:]]*\).md/\1.html/g' > README-mkinitcpio.html
+
+README-dracut.html: README-dracut.md
+ $(MD) README-dracut.md | $(SED) 's/\(README[-[:alnum:]]*\).md/\1.html/g' > README-dracut.html
install: install-mkinitcpio
@@ -33,9 +40,13 @@ install-bin: bin/ykfde udev/ykfde
$(INSTALL) -D -m0644 systemd/ykfde-cpio.service $(DESTDIR)/usr/lib/systemd/system/ykfde-cpio.service
$(INSTALL) -d -m0700 $(DESTDIR)/etc/ykfde.d/
-install-doc: README.md README.html
+install-doc: README.html README-mkinitcpio.html README-dracut.html
$(INSTALL) -D -m0644 README.md $(DESTDIR)/usr/share/doc/ykfde/README.md
$(INSTALL) -D -m0644 README.html $(DESTDIR)/usr/share/doc/ykfde/README.html
+ $(INSTALL) -D -m0644 README-mkinitcpio.md $(DESTDIR)/usr/share/doc/ykfde/README-mkinitcpio.md
+ $(INSTALL) -D -m0644 README-mkinitcpio.html $(DESTDIR)/usr/share/doc/ykfde/README-mkinitcpio.html
+ $(INSTALL) -D -m0644 README-dracut.md $(DESTDIR)/usr/share/doc/ykfde/README-dracut.md
+ $(INSTALL) -D -m0644 README-dracut.html $(DESTDIR)/usr/share/doc/ykfde/README-dracut.html
install-mkinitcpio: install-bin install-doc
$(INSTALL) -D -m0644 mkinitcpio/ykfde $(DESTDIR)/usr/lib/initcpio/install/ykfde
@@ -51,7 +62,10 @@ install-dracut: install-bin install-doc
clean:
$(MAKE) -C bin clean
$(MAKE) -C udev clean
- $(RM) -f README.html
+ $(RM) -f README.html README-mkinitcpio.html README-dracut.html
+
+distclean: clean
+ $(RM) -f config.h
release:
git archive --format=tar.xz --prefix=mkinitcpio-ykfde-$(VERSION)/ $(VERSION) > mkinitcpio-ykfde-$(VERSION).tar.xz
diff --git a/README-dracut.md b/README-dracut.md
new file mode 100644
index 0000000..bdbe718
--- /dev/null
+++ b/README-dracut.md
@@ -0,0 +1,65 @@
+Full disk encryption with Yubikey (Yubico key) for dracut
+=========================================================
+
+This allows to automatically unlock a LUKS encrypted hard disk from `systemd`-
+enabled initramfs.
+
+Requirements
+------------
+
+To compile and use yubikey full disk encryption you need:
+
+[...]
+
+Build and install
+-----------------
+
+Building and installing is very easy. Just run:
+
+> make
+
+followed by:
+
+> make install-dracut
+
+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.
+
+[...]
+
+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!
diff --git a/README-mkinitcpio.md b/README-mkinitcpio.md
new file mode 100644
index 0000000..8f25819
--- /dev/null
+++ b/README-mkinitcpio.md
@@ -0,0 +1,92 @@
+Full disk encryption with Yubikey (Yubico key) for mkinitcpio
+=============================================================
+
+This allows to automatically unlock a LUKS encrypted hard disk from `systemd`-
+enabled initramfs.
+
+Requirements
+------------
+
+To compile and use yubikey full disk encryption you need:
+
+* [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/)
+* [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-mkinitcpio
+
+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!
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