From f9dd1ce4dce33e5087393ef72877589d5f88ebd3 Mon Sep 17 00:00:00 2001 From: shimun Date: Wed, 24 Jun 2020 18:18:37 +0200 Subject: [PATCH] generate README from docs --- .drone.yml | 6 ++- README.md | 65 ++++++++++++++++--------------- README.tpl | 20 ++++++++++ src/main.rs | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 168 insertions(+), 31 deletions(-) create mode 100644 README.tpl diff --git a/.drone.yml b/.drone.yml index 0c3e955..8eef459 100644 --- a/.drone.yml +++ b/.drone.yml @@ -13,7 +13,11 @@ steps: - apt update && apt install -y libkeyutils-dev libclang-dev clang pkg-config - echo 'deb http://http.us.debian.org/debian unstable main non-free contrib' >> /etc/apt/sources.list.d/unstable.list && apt update && apt install -y libcryptsetup-dev - cargo test - + - name: readme + image: msrd0/cargo-readme@sha256:2b916451e576cda54f1e02703fa092b9d5af95bcf48426a1ef42872a19467fd3 + commands: + - cargo readme > ~README.md + - cmp -s README.md ~README.md || (printf "README.md need to be updated:\n"; cat ~README.md; exit 1) - name: publish image: rust:1.43.0 environment: diff --git a/README.md b/README.md index 6dfff16..b2b90a6 100644 --- a/README.md +++ b/README.md @@ -1,86 +1,75 @@ -# fido2luks [![Crates.io Version](https://img.shields.io/crates/v/fido2luks.svg)](https://crates.io/crates/fido2luks) +[![Crates.io](https://img.shields.io/crates/v/fido2luks.svg)](https://crates.io/crates/fido2luks) +# fido2luks This will allow you to unlock your luks encrypted disk with an fido2 compatible key Note: This has only been tested under Fedora 31 using a Solo Key, Trezor Model T -## Setup +### Setup -### Prerequisites +#### Prerequisites -``` +```rust dnf install clang cargo cryptsetup-devel -y ``` -### Device +#### Device -``` +```rust git clone https://github.com/shimunn/fido2luks.git && cd fido2luks -# Alternativly cargo build --release && sudo cp target/release/fido2luks /usr/bin/ sudo -E cargo install -f --path . --root /usr -# Copy template cp dracut/96luks-2fa/fido2luks.conf /etc/ -# Name is optional but useful if your authenticator has a display echo FIDO2LUKS_CREDENTIAL_ID=$(fido2luks credential [NAME]) >> /etc/fido2luks.conf -# Load config into env set -a . /etc/fido2luks.conf -# Repeat for each luks volume -# You can also use the `--token` flag when using LUKS2 which will then store the credential in the LUKS header, -# enabling you to use `fido2luks open-token` without passing a credential as parameter sudo -E fido2luks -i add-key /dev/disk/by-uuid/ -# Test(only works if the luks container isn't active) sudo -E fido2luks -i open /dev/disk/by-uuid/ luks- ``` -### Dracut +#### Dracut -``` +```rust cd dracut sudo make install ``` -### Grub +#### Grub Add `rd.luks.2fa=:` to `GRUB_CMDLINE_LINUX` in /etc/default/grub Note: This is only required for your root disk, systemd will try to unlock all other LUKS partions using the same key if you added it using `fido2luks add-key` -``` +```rust grub2-mkconfig > /boot/grub2/grub.cfg ``` I'd also recommend to copy the executable onto /boot so that it is accessible in case you have to access your disk from a rescue system -``` +```rust mkdir /boot/fido2luks/ cp /usr/bin/fido2luks /boot/fido2luks/ cp /etc/fido2luks.conf /boot/fido2luks/ ``` -## Test +### Test Just reboot and see if it works, if that's the case you should remove your old less secure password from your LUKS header: -``` -# Recommend in case you lose your authenticator, store this backupfile somewhere safe +```rust cryptsetup luksHeaderBackup /dev/disk/by-uuid/ --header-backup-file luks_backup_ -# There is no turning back if you mess this up, make sure you made a backup -# You can also pass `--token` if you're using LUKS2 which will then store the credential in the LUKS header, -# which will enable you to use `fido2luks open-token` without passing a credential as parameter fido2luks -i add-key --exclusive /dev/disk/by-uuid/ ``` -## Addtional settings +### Addtional settings -### Password less +#### Password less Remove your previous secret as described in the next section, in case you've already added one. @@ -89,21 +78,37 @@ but be warned that this password will be included to into your initramfs. Import the new config into env: -``` +```rust set -a . /etc/fido2luks.conf ``` Then add the new secret to each device and update dracut afterwards `dracut -f` -## Removal +### Removal Remove `rd.luks.2fa` from `GRUB_CMDLINE_LINUX` in /etc/default/grub -``` +```rust set -a . fido2luks.conf sudo -E fido2luks -i replace-key /dev/disk/by-uuid/ sudo rm -rf /usr/lib/dracut/modules.d/96luks-2fa /etc/dracut.conf.d/luks-2fa.conf /etc/fido2luks.conf ``` + +## License + +Licensed under either of + +* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0) +* MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT) + +at your option. + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally +submitted for inclusion in the work by you, as defined in the Apache-2.0 +license, shall be dual licensed as above, without any additional terms or +conditions. diff --git a/README.tpl b/README.tpl new file mode 100644 index 0000000..365b4d3 --- /dev/null +++ b/README.tpl @@ -0,0 +1,20 @@ +[![Crates.io](https://img.shields.io/crates/v/fido2luks.svg)](https://crates.io/crates/fido2luks) +# {{crate}} + +{{readme}} + +## License + +Licensed under either of + +* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0) +* MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT) + +at your option. + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally +submitted for inclusion in the work by you, as defined in the Apache-2.0 +license, shall be dual licensed as above, without any additional terms or +conditions. diff --git a/src/main.rs b/src/main.rs index 7c842d6..9cc6102 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,3 +1,111 @@ +//! This will allow you to unlock your luks encrypted disk with an fido2 compatible key +//! +//! Note: This has only been tested under Fedora 31 using a Solo Key, Trezor Model T +//! +//! ## Setup +//! +//! ### Prerequisites +//! +//! ``` +//! dnf install clang cargo cryptsetup-devel -y +//! ``` +//! +//! ### Device +//! +//! ``` +//! git clone https://github.com/shimunn/fido2luks.git && cd fido2luks +//! +//! # Alternativly cargo build --release && sudo cp target/release/fido2luks /usr/bin/ +//! sudo -E cargo install -f --path . --root /usr +//! +//! # Copy template +//! cp dracut/96luks-2fa/fido2luks.conf /etc/ +//! # Name is optional but useful if your authenticator has a display +//! echo FIDO2LUKS_CREDENTIAL_ID=$(fido2luks credential [NAME]) >> /etc/fido2luks.conf +//! +//! # Load config into env +//! set -a +//! . /etc/fido2luks.conf +//! +//! # Repeat for each luks volume +//! # You can also use the `--token` flag when using LUKS2 which will then store the credential in the LUKS header, +//! # enabling you to use `fido2luks open-token` without passing a credential as parameter +//! sudo -E fido2luks -i add-key /dev/disk/by-uuid/ +//! +//! # Test(only works if the luks container isn't active) +//! sudo -E fido2luks -i open /dev/disk/by-uuid/ luks- +//! +//! ``` +//! +//! ### Dracut +//! +//! ``` +//! cd dracut +//! +//! sudo make install +//! ``` +//! +//! ### Grub +//! +//! Add `rd.luks.2fa=:` to `GRUB_CMDLINE_LINUX` in /etc/default/grub +//! +//! Note: This is only required for your root disk, systemd will try to unlock all other LUKS partions using the same key if you added it using `fido2luks add-key` +//! +//! ``` +//! grub2-mkconfig > /boot/grub2/grub.cfg +//! ``` +//! +//! I'd also recommend to copy the executable onto /boot so that it is accessible in case you have to access your disk from a rescue system +//! +//! ``` +//! mkdir /boot/fido2luks/ +//! cp /usr/bin/fido2luks /boot/fido2luks/ +//! cp /etc/fido2luks.conf /boot/fido2luks/ +//! ``` +//! +//! ## Test +//! +//! Just reboot and see if it works, if that's the case you should remove your old less secure password from your LUKS header: +//! +//! ``` +//! # Recommend in case you lose your authenticator, store this backupfile somewhere safe +//! cryptsetup luksHeaderBackup /dev/disk/by-uuid/ --header-backup-file luks_backup_ +//! # There is no turning back if you mess this up, make sure you made a backup +//! # You can also pass `--token` if you're using LUKS2 which will then store the credential in the LUKS header, +//! # which will enable you to use `fido2luks open-token` without passing a credential as parameter +//! fido2luks -i add-key --exclusive /dev/disk/by-uuid/ +//! ``` +//! +//! ## Addtional settings +//! +//! ### Password less +//! +//! Remove your previous secret as described in the next section, in case you've already added one. +//! +//! Open `/etc/fido2luks.conf` and replace `FIDO2LUKS_SALT=Ask` with `FIDO2LUKS_SALT=string:` +//! but be warned that this password will be included to into your initramfs. +//! +//! Import the new config into env: +//! +//! ``` +//! set -a +//! . /etc/fido2luks.conf +//! ``` +//! +//! Then add the new secret to each device and update dracut afterwards `dracut -f` +//! +//! ## Removal +//! +//! Remove `rd.luks.2fa` from `GRUB_CMDLINE_LINUX` in /etc/default/grub +//! +//! ``` +//! set -a +//! . fido2luks.conf +//! sudo -E fido2luks -i replace-key /dev/disk/by-uuid/ +//! +//! sudo rm -rf /usr/lib/dracut/modules.d/96luks-2fa /etc/dracut.conf.d/luks-2fa.conf /etc/fido2luks.conf +//!``` + #[macro_use] extern crate failure; extern crate ctap_hmac as ctap;