docs: derive factors

Author: lonerapier

mfkdf2/src/derive/factors/hmacsha1.rs

@@ -1,3 +1,10 @@
+//! Factor construction derive phase for the HMAC‑SHA1 factor from
+//! [HMAC-SHA1](`crate::setup::factors::hmacsha1`).
+//!
+//! - During setup, the factor stores a padded HMAC key and a challenge in the policy.
+//! - During derive, this module consumes an HMAC response over that challenge and reconstructs the
+//!   same padded secret so that the factor contributes identical bytes to the MFKDF2 key
+//!   derivation.
 use serde_json::{Value, json};
 
 use crate::{
@@ -12,6 +19,7 @@ impl FactorDerive for HmacSha1 {
   type Output = Value;
   type Params = Value;
 
+  /// Includes the public parameters for in factor state and decrypts the secret material.
   fn include_params(&mut self, params: Self::Params) -> MFKDF2Result<()> {
     self.params = Some(serde_json::to_string(&params).unwrap());
 
@@ -34,6 +42,7 @@ impl FactorDerive for HmacSha1 {
     Ok(())
   }
 
+  /// Computes a new challenge and encrypts the secret material as pad for the factor.
   fn params(&self, _key: Key) -> MFKDF2Result<Self::Params> {
     let mut challenge = [0u8; 64];
     crate::rng::fill_bytes(&mut challenge);
@@ -56,6 +65,75 @@ impl FactorDerive for HmacSha1 {
   }
 }
 
+/// Factor construction derive phase for an HMAC‑SHA1 factor
+///
+/// The caller is expected to compute `response = HMAC-SHA1(secret, challenge)` using the secret
+/// key material stored by the application and the `challenge` value provided in the setup policy
+/// parameters. This helper wraps the response in an [`MFKDF2Factor`] witness Wᵢⱼ that, once
+/// combined with the policy via [`FactorDerive::include_params`], recovers the same padded secret
+/// as in setup.
+///
+/// # Errors
+///
+/// - [MFKDF2Error::MissingDeriveParams](`crate::error::MFKDF2Error::MissingDeriveParams`) if the
+///   setup policy omits the `"pad"` parameter when `include_params` is invoked
+/// - [MFKDF2Error::InvalidDeriveParams](`crate::error::MFKDF2Error::InvalidDeriveParams`) if the
+///   `"pad"` field is not valid hex or has an unexpected shape
+///
+/// # Example
+///
+/// Single‑factor setup and factor construction derive phase using the HMAC‑SHA1 factor within
+/// KeySetup/KeyDerive:
+///
+/// ```rust
+/// # use std::collections::HashMap;
+/// # use mfkdf2::{
+/// #   error::MFKDF2Result,
+/// #   setup::{
+/// #     self,
+/// #     factors::hmacsha1::{HmacSha1Options, hmacsha1 as setup_hmacsha1},
+/// #     key::MFKDF2Options,
+/// #   },
+/// #   derive,
+/// # };
+/// # use hmac::{Mac, Hmac};
+/// # use sha1::Sha1;
+/// # const HMACSHA1_SECRET: [u8; 20] = [0x11; 20];
+/// #
+/// # fn main() -> MFKDF2Result<()> {
+/// // KeySetup: build a policy with a single HMAC‑SHA1 factor
+/// let setup_factor = setup_hmacsha1(HmacSha1Options {
+///   secret: Some(HMACSHA1_SECRET.to_vec()),
+///   ..Default::default()
+/// })?;
+/// let setup_key = setup::key(&[setup_factor], MFKDF2Options::default())?;
+///
+/// // Read the challenge for this factor from the policy
+/// let policy_factor = setup_key.policy.factors.iter().find(|f| f.id == "hmacsha1").unwrap();
+/// let setup_params = &policy_factor.params;
+/// let challenge = hex::decode(setup_params["challenge"].as_str().unwrap()).unwrap();
+///
+/// // The hardware token (or equivalent) computes HMAC-SHA1 over the challenge
+/// let response: [u8; 20] = <Hmac<Sha1> as Mac>::new_from_slice(&HMACSHA1_SECRET)
+///   .unwrap()
+///   .chain_update(&challenge)
+///   .finalize()
+///   .into_bytes()
+///   .into();
+///
+/// // Build the derive‑time HMAC witness and run KeyDerive
+/// let derive_factor = crate::derive::factors::hmacsha1(response.into())?;
+/// let derived_key = derive::key(
+///   &setup_key.policy,
+///   HashMap::from([("hmacsha1".to_string(), derive_factor)]),
+///   true,
+///   false,
+/// )?;
+///
+/// assert_eq!(derived_key.key, setup_key.key);
+/// # Ok(())
+/// # }
+/// ```
 pub fn hmacsha1(response: HmacSha1Response) -> MFKDF2Result<MFKDF2Factor> {
   Ok(MFKDF2Factor {
     id:          None,

mfkdf2/src/derive/factors/hotp.rs

@@ -1,3 +1,10 @@
+//! This module constructs [`MFKDF2Factor`] witnesses Wᵢⱼ for the derive phase corresponding
+//! to the setup factors defined in [hotp](`crate::setup::factors::hotp`).
+//! - During setup, the HOTP factor chooses a secret target code and encodes an offset and encrypted
+//!   pad into the policy;
+//! - During derive, this module consumes the HOTP code Wᵢⱼ and reconstructs the same target value
+//!   using the stored offset so that the factor contributes stable material to the key derivation
+//!   while remaining backward‑compatible with existing OATH HOTP applications.
 use base64::Engine;
 use serde_json::{Value, json};
 
@@ -14,6 +21,7 @@ impl FactorDerive for HOTP {
   type Output = Value;
   type Params = Value;
 
+  /// Includes the public parameters for in factor state and calculates the target value.
   fn include_params(&mut self, params: Self::Params) -> MFKDF2Result<()> {
     // Store the policy parameters for derive phase
     self.params = params.clone();
@@ -28,13 +36,14 @@ impl FactorDerive for HOTP {
       let modulus = 10_u64.pow(digits);
       let target = (u64::from(offset) + u64::from(self.code)) % modulus;
 
-      // Store target as 4-byte big-endian (matches JS implementation)
+      // Store target as 4-byte big-endian
       self.target = target as u32;
     }
 
     Ok(())
   }
 
+  /// Decrypts the secret and generates a new HOTP code with incremented counter.
   fn params(&self, key: Key) -> MFKDF2Result<Self::Params> {
     let params: HOTPParams = serde_json::from_value(self.params.clone())?;
 
@@ -61,6 +70,74 @@ impl FactorDerive for HOTP {
   }
 }
 
+/// HOTP factor construction derive phase
+///
+/// The code should be the numeric one‑time password displayed by an authenticator app that has
+/// been paired with the HOTP secret configured during setup.
+///
+/// # Errors
+///
+/// - [`MFKDF2Error::Serialize`](`crate::error::MFKDF2Error::Serialize`) if the stored policy
+///   parameters cannot be decoded into [HOTPParams](`crate::setup::factors::hotp::HOTPParams`) (for
+///   example, missing or malformed fields)
+///
+/// # Example
+///
+/// Single‑factor setup/derive using HOTP within KeySetup/KeyDerive:
+///
+/// ```rust
+/// # use std::collections::HashMap;
+/// # use mfkdf2::{
+/// #   error::MFKDF2Result,
+/// #   otpauth::HashAlgorithm,
+/// #   setup::{
+/// #     self,
+/// #     factors::hotp::{HOTPOptions, hotp as setup_hotp},
+/// #     key::MFKDF2Options,
+/// #   },
+/// #   derive,
+/// # };
+/// #
+/// # fn main() -> MFKDF2Result<()> {
+/// let secret = b"hello world mfkdf2!!".to_vec();
+/// let options = HOTPOptions {
+///   id: Some("hotp".to_string()),
+///   secret: Some(secret),
+///   digits: Some(6),
+///   hash: Some(HashAlgorithm::Sha1),
+///   ..Default::default()
+/// };
+///
+/// let setup_factor = setup_hotp(options)?;
+/// let hotp = if let mfkdf2::definitions::FactorType::HOTP(ref h) = setup_factor.factor_type {
+///   h.clone()
+/// } else {
+///   unreachable!()
+/// };
+/// let setup_key = setup::key(&[setup_factor], MFKDF2Options::default())?;
+///
+/// let policy_factor = setup_key.policy.factors.iter().find(|f| f.id == "hotp").unwrap();
+/// let params = &policy_factor.params;
+/// let counter = params["counter"].as_u64().unwrap();
+/// let code = mfkdf2::otpauth::generate_otp_token(
+///   &hotp.config.secret[..20],
+///   counter,
+///   &hotp.config.hash,
+///   hotp.config.digits,
+/// );
+///
+/// let derive_factor = crate::derive::factors::hotp(code)?;
+/// let derived_key = derive::key(
+///   &setup_key.policy,
+///   HashMap::from([("hotp".to_string(), derive_factor)]),
+///   true,
+///   false,
+/// )?;
+///
+/// assert_eq!(derived_key.key, setup_key.key);
+/// # Ok(())
+/// # }
+/// ```
 pub fn hotp(code: u32) -> MFKDF2Result<MFKDF2Factor> {
   // Create HOTP factor with the user-provided code
   // The target will be calculated in include_params once we have the policy parameters

mfkdf2/src/derive/factors/mod.rs

@@ -1,3 +1,17 @@
+//! Factor construction derive phase
+//!
+//! This module constructs [`MFKDF2Factor`] witnesses Wᵢⱼ for the derive phase corresponding
+//! to the setup factors defined in [`crate::setup::factors`]. Each helper takes respective factor
+//! secret (such as a password, OTP code, UUID, or passkey secret) plus any derive-specific options
+//! and constructs a [`MFKDF2Factor`] that is used in [`crate::derive::key`] derivation.
+//!
+//! During the KeyDerive phase, these factors combine with the public policy state βᵢ to reconstruct
+//! the underlying static source material κⱼ and ultimately recover the master secret `M` and next
+//! derived key state βᵢ₊₁.
+//!
+//! **Note:** Factor setup/derive individually are not intended to be used in isolation, but are
+//! composed through [`crate::setup::key`] (Setup) and [`crate::derive::key`] (Derive),
+//! respectively, where factors supply witness material for the overall multi‑factor policy.
 mod hmacsha1;
 mod hotp;
 mod ooba;

mfkdf2/src/derive/factors/ooba.rs

@@ -1,3 +1,9 @@
+//! This module implements the factor construction derive phase for the OOBA construction from
+//! `crate::setup::factors::ooba`.
+//! - During setup, the factor samples a random 32‑byte target, encrypts it under a channel‑specific
+//!   RSA key, and embeds an initial code and metadata in the policy.
+//! - During derive, this module consumes a user‑entered OOBA code Wᵢⱼ, decrypts the target using
+//!   the stored pad, and prepares the next encrypted payload and code for the following login
 use base64::{Engine, engine::general_purpose};
 use rsa::Oaep;
 use serde_json::{Value, json};
@@ -15,6 +21,8 @@ impl FactorDerive for Ooba {
   type Output = Value;
   type Params = Value;
 
+  /// Includes the public parameters for in factor state and decrypts the secret material from
+  /// public parameters.
   fn include_params(&mut self, params: Self::Params) -> MFKDF2Result<()> {
     let pad_b64 =
       params["pad"].as_str().ok_or(MFKDF2Error::MissingDeriveParams("pad".to_string()))?;
@@ -42,6 +50,7 @@ impl FactorDerive for Ooba {
     Ok(())
   }
 
+  /// Generates a new OOBA code and encrypts the secret material for the next derivation.
   fn params(&self, _key: Key) -> MFKDF2Result<Self::Params> {
     let code = generate_alphanumeric_characters(self.length.into()).to_uppercase();
 
@@ -67,6 +76,87 @@ impl FactorDerive for Ooba {
   }
 }
 
+/// Factor construction derive phase for an OOBA factor
+///
+/// The `code` should be the alphanumeric value delivered over the out‑of‑band channel (for example,
+/// SMS or push notification) that corresponds to the initial OOBA policy parameters created during
+/// setup.
+///
+/// # Errors
+///
+/// - [`MFKDF2Error::InvalidOobaCode`] if `code` is empty
+/// - [`MFKDF2Error::MissingDeriveParams`] from [`FactorDerive::include_params`] when required
+///   fields such as `"pad"` or `"length"` are absent in the policy parameters
+/// - [`MFKDF2Error::InvalidDeriveParams`] from [`FactorDerive::include_params`] when fields such as
+///   `"pad"`, `"params"`, or `"key"` are malformed or have the wrong type
+///
+/// # Example
+///
+/// Single‑factor setup/derive using OOBA within KeySetup/KeyDerive:
+///
+/// ```rust
+/// # use std::collections::HashMap;
+/// # use jsonwebtoken::jwk::Jwk;
+/// # use rsa::{RsaPrivateKey, RsaPublicKey, traits::PublicKeyParts};
+/// # use serde_json::json;
+/// # use mfkdf2::{
+/// #   error::MFKDF2Result,
+/// #   setup::{
+/// #     self,
+/// #     factors::ooba::{ooba as setup_ooba, OobaOptions},
+/// #     key::MFKDF2Options,
+/// #   },
+/// #   derive,
+/// # };
+/// # use mfkdf2::derive::factors::ooba as derive_ooba;
+/// # use base64::Engine;
+/// # use sha2::Sha256;
+/// # use rsa::Oaep;
+/// #
+/// # fn main() -> MFKDF2Result<()> {
+/// let bits = 2048;
+/// let private_key =
+///   RsaPrivateKey::new(&mut rsa::rand_core::OsRng, bits).expect("failed to generate a key");
+/// let public_key = RsaPublicKey::from(&private_key);
+///
+/// let n = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(public_key.n().to_bytes_be());
+/// let e = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(public_key.e().to_bytes_be());
+/// let jwk: Jwk = serde_json::from_value(json!({
+///   "kty": "RSA",
+///   "alg": "RSA-OAEP-256",
+///   "n": n,
+///   "e": e
+/// }))?;
+///
+/// let setup_factor = setup_ooba(OobaOptions {
+///   id:     Some("ooba".into()),
+///   length: Some(8),
+///   key:    Some(jwk),
+///   params: Some(json!({"foo": "bar"})),
+/// })?;
+/// let setup_key = setup::key(&[setup_factor], MFKDF2Options::default())?;
+///
+/// // Decrypt the first OOBA payload to recover the user-visible code
+/// let policy_factor =
+///   setup_key.policy.factors.iter().find(|f| f.id == "ooba").unwrap();
+/// let setup_params = &policy_factor.params;
+/// let ciphertext = hex::decode(setup_params["next"].as_str().unwrap()).unwrap();
+/// let plaintext = private_key.decrypt(Oaep::new::<Sha256>(), &ciphertext).unwrap();
+/// let decoded: serde_json::Value = serde_json::from_slice(&plaintext).unwrap();
+/// let code = decoded["code"].as_str().unwrap();
+///
+/// let derive_factor = derive_ooba(code)?;
+/// let derived_key = derive::key(
+///   &setup_key.policy,
+///   HashMap::from([("ooba".to_string(), derive_factor)]),
+///   true,
+///   false,
+/// )?;
+///
+/// assert_eq!(derived_key.key, setup_key.key);
+/// # Ok(())
+/// # }
+/// ```
 pub fn ooba(code: &str) -> MFKDF2Result<MFKDF2Factor> {
   if code.is_empty() {
     return Err(MFKDF2Error::InvalidOobaCode);