WIP documentation

Missing some in TOTP, but I need to sleep

Author: orion78fr

src/hotp.rs

@@ -4,9 +4,8 @@ use crate::util::{base32_decode, get_code, hash_generic, MacDigest};
 
 /// A HOTP Generator
 ///
-/// Follows the specification listed in [RFC4226]. Needs a secret on
-/// initialization, with other single generation-specific items being
-/// provided when [`HOTP::get_otp`] is called.
+/// Follows the specification listed in [RFC4226]. Needs a secret and a number of digits on initialization.
+/// The HOTP can then be generated using [`HOTP::get_otp`].
 ///
 /// # Example
 /// See the top-level README for an example of HOTP usage
@@ -21,65 +20,69 @@ pub struct HOTP {
     /// The secret key used in the HMAC process.
     ///
     /// Often given as a Base32 key, which can be conveniently initialize using
-    /// the [`HOTP::from_base32`] initializers
+    /// the [`HOTP::from_base32`] constructors.
     secret: Vec<u8>,
 
+    /// The number of digits of the code generated.
+    ///
+    /// This value defaults to 6 if not specified in a constructor.
     digits: u32,
 }
 
 /// All initializer implementations for the [`HOTP`] struct.
 impl HOTP {
     /// Creates a new HOTP instance with a byte-array representation
-    /// of the secret
+    /// of the secret and the number of digits.
     ///
     /// Since only SHA1 was specified in the reference implementation and
-    /// RFC specification, there's no need to initialize with a digest object
+    /// RFC specification, there's no need to initialize with a digest object.
     pub fn new(secret: &[u8], digits: u32) -> Self {
         HOTP {
             secret: secret.to_vec(),
             digits,
         }
     }
 
+    /// Creates a new HOTP instance from a utf8-encoded string secret and the number of digits.
     pub fn new_from_utf8(secret: &str, digits: u32) -> Self {
         HOTP::new(secret.as_bytes(), digits)
     }
 
+    /// Creates a new HOTP instance from a base32-encoded string secret and the number of digits.
+    ///
+    /// # Panics
+    /// This method panics if the provided string is not correctly base32 encoded.
     pub fn new_from_base32(secret: &str, digits: u32) -> Self {
         let decoded = base32_decode(secret).expect("Failed to decode base32 string");
         HOTP::new(&decoded, digits)
     }
 
-    /// Creates a new HOTP instance from a utf8-encoded string secret
-    ///
-    /// Internally calls [`HOTP::new`] with the string's byte representation
+    /// Creates a new HOTP instance from a utf8-encoded string secret and a default number of 6 digits.
     pub fn from_utf8(secret: &str) -> Self {
         HOTP::new_from_utf8(secret, 6)
     }
 
-    /// Creates a new HOTP instance from a base32-encoded string secret
-    ///
-    /// Internally calls [`HOTP::new`] after decoding the string
+    /// Creates a new HOTP instance from a base32-encoded string secret and a default number of 6 digits.
     ///
     /// # Panics
-    /// This method panics if the provided string is not correctly base32
-    /// encoded.
+    /// This method panics if the provided string is not correctly base32 encoded.
     pub fn from_base32(secret: &str) -> Self {
         HOTP::new_from_base32(secret, 6)
     }
 }
 
 impl HOTP {
+    /// Gets the number of digits of the code.
     pub fn get_digits(&self) -> u32 {
         self.digits
     }
 }
 
 /// All otp generation methods for the [`HOTP`] struct.
 impl HOTP {
-    /// Generates and returns the HOTP value
+    /// Generates and returns the HOTP value.
     ///
-    /// Uses the given counter value with the specified digit count
+    /// Uses the given counter value.
     ///
     /// # Panics
     /// This method panics if the hash's secret is incorrectly given.

src/totp.rs

@@ -2,10 +2,10 @@ use crate::util::{base32_decode, get_code, hash_generic, MacDigest};
 
 /// A TOTP generator
 ///
-/// Follows the specification listed in [RFC6238]. Needs a secret
-/// and digest algorithm on initialization, with other single
-/// generation-specific items being provided when the [`TOTP::get_otp`] or
-/// [`TOTP::get_otp_with_custom`] is called.
+/// Follows the specification listed in [RFC6238]. Needs a secret,
+/// a digest algorithm, a number of digits and a period on initialization.
+/// The TOTP can then be generated using [`TOTP::get_otp`] or
+/// [`TOTP::get_otp_with_custom_time_start`].
 ///
 /// # Example
 /// See the top-level README for an example of TOTP usage
@@ -14,28 +14,31 @@ use crate::util::{base32_decode, get_code, hash_generic, MacDigest};
 /// utilized in a similar manner.
 ///
 /// [RFC6238]: https://datatracker.ietf.org/doc/html/rfc6238
-
 #[derive(Debug, Clone, Hash)]
 pub struct TOTP {
     /// The secret key used in the HMAC process.
     ///
-    /// Often given as a Base32 key, which can be conveniently initialize using
-    /// the [`TOTP::from_base32`] or [`TOTP::from_base32_with_digest`]
-    /// initializers.
+    /// Often given as a Base32 key, which can be conveniently initialized using
+    /// [`TOTP::from_base32`] constructors.
     secret: Vec<u8>,
 
     /// The digest to use in the HMAC process.
     ///
-    /// Unless an initializer ending in 'with_digest' is used, this value
-    /// defaults to [`MacDigest::SHA1`]
+    /// This value defaults to [`MacDigest::SHA1`] if not specified in a constructor.
     mac_digest: MacDigest,
 
+    /// The number of digits of the code generated.
+    ///
+    /// This value defaults to 6 if not specified in a constructor.
     digits: u32,
 
+    /// The period in seconds between two different generated code.
+    ///
+    /// This value defaults to 30 if not specified in a constructor.
     period: u64,
 }
 
-/// All initializer implementations for the [`TOTP`] struct
+// All initializer implementations for the [`TOTP`] struct
 impl TOTP {
     pub fn new(secret: &[u8], mac_digest: MacDigest, digits: u32, period: u64) -> Self {
         TOTP {
@@ -112,21 +115,25 @@ impl TOTP {
     }
 }
 
+// All getters
 impl TOTP {
+    /// Gets the algorithm used for code generation.
     pub fn get_digest(&self) -> MacDigest {
         self.mac_digest
     }
 
+    /// Gets the number of digits of the code.
     pub fn get_digits(&self) -> u32 {
         self.digits
     }
 
+    /// Gets the period between different generated code.
     pub fn get_period(&self) -> u64 {
         self.period
     }
 }
 
-/// All otp generation methods for the [`TOTP`] struct.
+// All otp generation methods for the [`TOTP`] struct.
 impl TOTP {
     /// Generates and returns the TOTP value for the time with the
     /// specified digits.

src/util.rs

@@ -8,7 +8,7 @@ use url::Url;
 use crate::hotp::HOTP;
 use crate::totp::TOTP;
 
-/// The digest to use with TOTP
+/// The digest to use with TOTP.
 ///
 /// All three digests referenced in [RFC6238] are supported:
 /// - SHA1
@@ -27,10 +27,9 @@ pub enum MacDigest {
 }
 
 /// A generic method to convert the [H/T]OTP byte-array into the
-/// requested decimal-based code
+/// requested decimal-based code.
 ///
-/// Needs the bytes to convert and the amount of digits the code should be
-
+/// Needs the bytes to convert and the amount of digits the code should be.
 pub(crate) fn get_code(bytes: [u8; 4], digits: u32) -> u32 {
     let code = (((bytes[0] & 0x7f) as u32) << 24)
         | ((bytes[1] as u32) << 16)
@@ -42,11 +41,10 @@ pub(crate) fn get_code(bytes: [u8; 4], digits: u32) -> u32 {
 /// A method to hash a message with a given secret and digest.
 ///
 /// The only time [`MacDigest`] is not [`MacDigest::SHA1`] is when the
-/// TOTP instance's mac_digest is set otherwise
+/// TOTP instance's mac_digest is set otherwise.
 ///
 /// Calls the underlying [`hash_internal`] function with the correctly
 /// HMAC-mapped algorithm.
-
 pub(crate) fn hash_generic(msg: &[u8], secret: &[u8], digest: &MacDigest) -> Vec<u8> {
     match *digest {
         MacDigest::SHA1 => hash_internal::<Hmac<Sha1>>(msg, secret),
@@ -55,32 +53,36 @@ pub(crate) fn hash_generic(msg: &[u8], secret: &[u8], digest: &MacDigest) -> Vec
     }
 }
 
-/// A generic method to HMAC a message using the given type
+/// A generic method to HMAC a message using the given type.
 ///
 /// This is mainly a private method made for added convenience and code
 /// readability to reduce the duplicate code with different
-/// underlying digests
+/// underlying digests.
 ///
 /// # Panics
 /// The method will panic if the provided secret is invalid and a hash
-/// cannot be generated
-
+/// cannot be generated.
 fn hash_internal<D: Mac>(msg: &[u8], secret: &[u8]) -> Vec<u8> {
     let mut hmac = <D>::new_from_slice(secret).expect("Failed to initialize HMAC");
     hmac.update(msg);
     hmac.finalize().into_bytes()[..].into()
 }
 
+/// Decodes a base32 string according to RFC4648.
 pub(crate) fn base32_decode(data: &str) -> Option<Vec<u8>> {
     base32::decode(Alphabet::RFC4648 { padding: false }, data)
 }
 
+/// Result of an otpauth URI parsing.
+///
+/// It's either a TOTP or a HOTP with its current counter.
 #[derive(Debug)]
 pub enum ParseResult {
     TOTP(TOTP),
     HOTP(HOTP, u64),
 }
 
+/// Different error types of the optauth URI parsing.
 #[derive(Debug)]
 pub enum ParseError {
     UriParseError(url::ParseError),
@@ -96,6 +98,8 @@ pub enum ParseError {
     InvalidPeriod(String),
 }
 
+/// Parses an otpauth URI, which is the string format of the QR codes usually given by platforms for TOTP.
+/// This method is safe and shouldn't panic.
 pub fn parse_otpauth_uri(uri: &str) -> Result<ParseResult, ParseError> {
     use ParseError::*;