diff options
| -rw-r--r-- | .gitignore | 2 | ||||
| -rw-r--r-- | Makefile | 28 | ||||
| -rw-r--r-- | README-dracut.md | 65 | ||||
| -rw-r--r-- | README-mkinitcpio.md | 92 | ||||
| -rw-r--r-- | README.md | 100 |
5 files changed, 191 insertions, 96 deletions
@@ -1,5 +1,5 @@ config.h -README.html bin/ykfde bin/ykfde-cpio udev/ykfde +*.html @@ -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! @@ -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 |