src/cli.rs

@@ -1,3 +1,44 @@
+//! ## 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 a 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
+
 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")]