generate README from docs

switch to license compatible with all dependencies

.drone.yml

@@ -7,13 +7,17 @@ steps:
    commands:
      -  rustup component add rustfmt
      -  cargo fmt --all -- --check
+ - 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: test
    image: rust:1.43.0
    commands:
     - 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: publish
    image: rust:1.43.0
    environment:
@@ -27,3 +31,4 @@ steps:
     - cargo publish --all-features
    when:
     event: tag
+   depends_on: ["fmt", "test", "readme"]

Cargo.toml

@@ -11,7 +11,7 @@ repository = "https://github.com/shimunn/fido2luks"
 readme = "README.md"
 keywords = ["luks", "fido2", "u2f"]
 categories = ["command-line-utilities"]
-license-file = "LICENSE"
+license = "MPL 2.0"
 
 [dependencies]
 ctap_hmac = { version="0.4.2", features = ["request_multiple"] }

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, [Ubuntu 20.04](initramfs-tools/), [NixOS](https://nixos.org/nixos/manual/#sec-luks-file-systems-fido2) 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/<DISK_UUID>
 
-# Test(only works if the luks container isn't active)
 sudo -E fido2luks -i open /dev/disk/by-uuid/<DISK_UUID> luks-<DISK_UUID>
 
 ```
 
-### Dracut
+#### Dracut
 
-```
+```rust
 cd dracut
 
 sudo make install
 ```
 
-### Grub
+#### Grub
 
 Add `rd.luks.2fa=<CREDENTIAL_ID>:<DISK_UUID>` 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:
 
-```
+```rust
-# Recommend in case you lose your authenticator, store this backupfile somewhere safe
 cryptsetup luksHeaderBackup /dev/disk/by-uuid/<DISK_UUID> --header-backup-file luks_backup_<DISK_UUID>
-# 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/<DISK_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,32 @@ 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/<DISK_UUID>
 
 sudo rm -rf /usr/lib/dracut/modules.d/96luks-2fa /etc/dracut.conf.d/luks-2fa.conf /etc/fido2luks.conf
 ```
+
+## License
+
+Licensed under the Mozilla Public License 2.0, ([LICENSE-MPL](LICENSE) or https://www.mozilla.org/en-US/MPL/2.0/)
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally
+submitted for inclusion in the work by you, as defined in the MPL 2.0
+license, shall be dual licensed as above, without any additional terms or
+conditions.

README.tpl

@@ -0,0 +1,15 @@
+[![Crates.io](https://img.shields.io/crates/v/fido2luks.svg)](https://crates.io/crates/fido2luks)
+# {{crate}}
+
+{{readme}}
+
+## License
+
+Licensed under the Mozilla Public License 2.0, ([LICENSE-MPL](LICENSE) or https://www.mozilla.org/en-US/MPL/2.0/)
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally
+submitted for inclusion in the work by you, as defined in the MPL 2.0
+license, shall be dual licensed as above, without any additional terms or
+conditions.

src/cli.rs

@@ -1,3 +1,54 @@
+//! ## Command line interface
+//! ### Generating a credential
+//! Credentials can be generated by using `fido2luks credential`
+//! this command will take an optional string as username your authenticator might be able to display
+//!
+//! `fido2luks credential 'My 2FA protected disk'`
+//!
+//! It is advisable to repeat this step and the next step for more than one authenticator, as backup
+//! ### Securing a disk
+//! To utilise the previously generated credential you simply run
+//!
+//! `fido2luks -i add-key <device> [<credential>,..]`
+//!
+//! You can also use `fido2luks -i add-key --exclusive <device> [<credential>,..]`
+//!
+//! which will add a new key and then remove ALL other keys.
+//! This command supports a fair amount of options for instance `--keyfile` which will allow you to
+//! add an authenticator to the `<device>`
+//!
+//! `-f` will utilise an previously added fido protected key to add another one
+//!
+//! `--token` will store the credential within the LUKS header, making it easily accessible even if
+//! you're unable to boot your system.
+//!
+//!
+//! `fido2luks -i replace-key <device> [<credential>,..]`
+//! works in a similar fashion but instead of adding a new key it'll update an existing one
+//!
+//!
+//! ### Unlocking a disk
+//! To open an LUKS container using your authenticator you simply run
+//!
+//! `fido2luks -i open <device> <name> [<credential>,..]`
+//!
+//! if successful your LUKS container will be accessible under `/dev/mapper/<name>`
+//! To avoid having to specify your credentials you may want to to use
+//!
+//! `fido2luks -i open-token <device> <name>`
+//!
+//! which should even be faster since it allows for the credential to be matched to the right keyslot
+//!
+//!
+//! ### Common options
+//!
+//! `--salt` Determines what data will be provided to the authenticator in order to derive the secret, the default being `ask` which will prompt the user for an password.
+//! Alternatives being `file:<PATH>` where the specified file will be hashed and then used as input, the same goes for the `string:<STRING>` option which will behave in the same manner as the `ask` option.
+//!
+//! `--pin` Allows for a PIN to be passed to the authenticator if needed, it is however recommended not to use a PIN since the bootscript doesn't support this feature atm.
+//!
+//! `--help` Will provide context dependant help for each command
+
 use crate::error::*;
 use crate::*;
 

src/luks.rs

@@ -11,7 +11,7 @@ pub struct LuksDevice {
     device: CryptDevice,
     luks2: Option<bool>,
 }
-
+/// Wrapper around [CryptDevice](libcryptsetup_rs::CryptDevice)
 impl LuksDevice {
     pub fn load<P: AsRef<Path>>(path: P) -> Fido2LuksResult<LuksDevice> {
         let mut device = CryptInit::init(path.as_ref())?;
@@ -22,6 +22,7 @@ impl LuksDevice {
         })
     }
 
+    /// Check whether the device supports LUKS2
     pub fn is_luks2(&mut self) -> Fido2LuksResult<bool> {
         if let Some(luks2) = self.luks2 {
             Ok(luks2)
@@ -34,6 +35,7 @@ impl LuksDevice {
         }
     }
 
+    /// Check whether the device supports LUKS2, return an appropriate error if it does not
     fn require_luks2(&mut self) -> Fido2LuksResult<()> {
         if !self.is_luks2()? {
             return Err(LuksError::Luks2Required.into());
@@ -41,6 +43,7 @@ impl LuksDevice {
         Ok(())
     }
 
+    /// Returns an iterator over all tokens, of type fido2luks
     pub fn tokens<'a>(
         &'a mut self,
     ) -> Fido2LuksResult<Box<dyn Iterator<Item = Fido2LuksResult<(u32, Fido2LuksToken)>> + 'a>>
@@ -84,6 +87,7 @@ impl LuksDevice {
         ))
     }
 
+    /// Returns the first token with an reference to the specified keyslot
     pub fn find_token(&mut self, slot: u32) -> Fido2LuksResult<Option<(u32, Fido2LuksToken)>> {
         let slot_str = slot.to_string();
         for token in self.tokens()? {
@@ -122,6 +126,8 @@ impl LuksDevice {
         Ok(())
     }
 
+    /// Add a new key `secret` using `old_secret` with the specified `iteration_time` in milliseconds
+    /// an LUKS2 token will be created if the device supports LUKS2 and a `credential_id` is provided
     pub fn add_key(
         &mut self,
         secret: &[u8],
@@ -175,6 +181,8 @@ impl LuksDevice {
         Ok(destroyed)
     }
 
+    /// Replaces an existing key with `secret` using `old_secret` with the specified `iteration_time` in milliseconds
+    /// an LUKS2 token will be created or updated if the device supports LUKS2 and a `credential_id` is provided
     pub fn replace_key(
         &mut self,
         secret: &[u8],
@@ -285,6 +293,7 @@ impl LuksDevice {
     }
 }
 
+/// Represents a LUKS2 token
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Fido2LuksToken {
     #[serde(rename = "type")]

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, [Ubuntu 20.04](initramfs-tools/), [NixOS](https://nixos.org/nixos/manual/#sec-luks-file-systems-fido2) 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/<DISK_UUID>
+//!
+//! # Test(only works if the luks container isn't active)
+//! sudo -E fido2luks -i open /dev/disk/by-uuid/<DISK_UUID> luks-<DISK_UUID>
+//!
+//! ```
+//!
+//! ### Dracut
+//!
+//! ```
+//! cd dracut
+//!
+//! sudo make install
+//! ```
+//!
+//! ### Grub
+//!
+//! Add `rd.luks.2fa=<CREDENTIAL_ID>:<DISK_UUID>` 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/<DISK_UUID> --header-backup-file luks_backup_<DISK_UUID>
+//! # 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/<DISK_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:<YOUR_RANDOM_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/<DISK_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;