Merge branch 'main' into add-repr-c

# Conflicts:
#	src/util.rs

Author: tmthecoder

Cargo.toml

@@ -4,10 +4,10 @@ description = "An easy-to-use library for HOTP and TOTP authentication"
 repository = "https://github.com/tmthecoder/xotp"
 readme = "README.md"
 license = "MIT"
-keywords = ["otp", "hotp", "totp"]
+keywords = ["otp", "hotp", "totp", "otpauth"]
 categories = ["cryptography"]
 authors = ["Tejas Mehta <[email protected]>"]
-version = "0.1.0"
+version = "0.2.0"
 edition = "2021"
 
 [features]
@@ -18,4 +18,5 @@ ffi = []
 hmac = "0.12.0"
 sha-1 = "0.10.0"
 sha2 = "0.10.1"
-base32 = "0.4.0"
+base32 = "0.4.0"
+url = "2.2.2"

README.md

@@ -25,51 +25,50 @@ fn get_otp_with_hotp() {
     let secret = "secret";
     let counter = 0;
     // Get a HOTP instance with a '&str' secret
-    let hotp_str = HOTP::from_utf8(secret);
-    // Get an otp with the given counter and digit count
-    let otp_from_str = hotp_str.get_otp(counter, 6);
+    let hotp_str = HOTP::default_from_utf8(secret);
+    // Get an otp with the given counter
+    let otp_from_str = hotp_str.get_otp(counter);
     println!("The otp from hotp_str: {}", otp_from_str);
-    
+
     // Alternatively, get a HOTP instance with a '&[u8]' secret
-    let hotp_bytes = HOTP::new(secret.as_bytes());
-    // Get an otp with the given counter and digit count
-    let otp_from_bytes = hotp_bytes.get_otp(counter, 6);
+    let hotp_bytes = HOTP::new(secret.as_bytes(), 6);
+    // Get an otp with the given counter
+    let otp_from_bytes = hotp_bytes.get_otp(counter);
     println!("The otp from hotp_bytes: {}", otp_from_bytes);
-} 
+}
 ```
 
 To use TOTP:
 
 ```rust
 use xotp::totp::TOTP;
-use xotp::util::MacDigest;
-// Only needed if using a non-SHA1 hash function
+use xotp::util::MacDigest; // Only needed if using a non-SHA1 hash function
 use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
 fn get_otp_with_totp() {
     let secret = "secret";
     let elapsed_seconds = SystemTime::now()
-        .duration_since(SystemTime::UNIX_EPOCH)
+        .duration_since(UNIX_EPOCH)
         .expect("Error getting time")
         .as_secs();
-    // Get a TOTP instance a '&str' secret and default SHA1 Digest
-    let totp_sha1_str = TOTP::from_utf8(secret);
-    // Get an otp with the given counter and elapsed seconds 
-    let otp_sha1 = totp_sha1_str.get_otp(elapsed_seconds, 8);
+    // Get a TOTP instance with an '&str' secret and default SHA1 Digest
+    let totp_sha1_str = TOTP::default_from_utf8(secret);
+    // Get an otp with the given counter and elapsed seconds
+    let otp_sha1 = totp_sha1_str.get_otp(elapsed_seconds);
     println!("The otp from totp_sha1_str: {}", otp_sha1);
 
-    // Alternatively get a TOTP instance with a '&[u8]' secret
+    // Alternatively get a TOTP instance with an '&[u8]' secret
     // and different digest (Sha256 or Sha512)
-    let totp_sha256_bytes = TOTP::new_with_digest(
+    let totp_sha256_bytes = TOTP::new(
         secret.as_bytes(),
-        MacDigest::SHA256
+        MacDigest::SHA256, // SHA256 algorithm
+        8,  // 8 digits
+        60  // 60-second interval
     );
     // Get an otp with the given counter, time and other custom params
-    let otp_sha256 = totp_sha256_bytes.get_otp_with_custom(
+    let otp_sha256 = totp_sha256_bytes.get_otp_with_custom_time_start(
         elapsed_seconds,
-        30, // A 60-second time step
         0, // Start time at unix epoch
-        6 // 8-digit code
     );
     println!("The otp from totp_sha256_bytes: {}", otp_sha256);
 }

src/hotp.rs

@@ -1,13 +1,11 @@
 // Implementation of the HOTP standard according to RFC4226 by Tejas Mehta
 
-use crate::util::{get_code, hash_generic, MacDigest};
-use base32::Alphabet;
+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
@@ -23,61 +21,85 @@ 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
-    pub fn new(secret: &[u8]) -> Self {
+    /// 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
-    ///
-    /// Internally calls [`HOTP::new`] with the string's byte representation
-    pub fn from_utf8(secret: &str) -> Self {
-        HOTP::new(secret.as_bytes())
+    /// Creates a new HOTP instance from an 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
+    /// Creates a new HOTP instance from a base32-encoded string secret and the number of digits.
     ///
-    /// Internally calls [`HOTP::new`] after decoding the string
+    /// # 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 byte-array representation of the secret and
+    /// a default number of 6 digits.
+    pub fn default_from_secret(secret: &[u8]) -> Self {
+        HOTP::new(secret, 6)
+    }
+
+    /// Creates a new HOTP instance from an utf8-encoded string secret and a default number of 6 digits.
+    pub fn default_from_utf8(secret: &str) -> Self {
+        HOTP::new_from_utf8(secret, 6)
+    }
+
+    /// 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.
-    pub fn from_base32(secret: &str) -> Self {
-        let decoded = base32::decode(Alphabet::RFC4648 { padding: false }, secret)
-            .expect("Failed to decode base32 string");
-        HOTP::new(&decoded)
+    /// This method panics if the provided string is not correctly base32 encoded.
+    pub fn default_from_base32(secret: &str) -> Self {
+        HOTP::new_from_base32(secret, 6)
     }
 }
 
-/// All otp generation methods for the [`HOTP`] struct.
+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.
-    pub fn get_otp(&self, counter: u64, digits: u32) -> u32 {
+    pub fn get_otp(&self, counter: u64) -> u32 {
         let hash = hash_generic(&counter.to_be_bytes(), &self.secret, &MacDigest::SHA1);
         let offset = (hash[hash.len() - 1] & 0xf) as usize;
         let bytes: [u8; 4] = hash[offset..offset + 4]
             .try_into()
             .expect("Failed byte get");
 
-        get_code(bytes, digits)
+        get_code(bytes, self.digits)
     }
 }

src/lib.rs

@@ -14,15 +14,15 @@
 //!     let secret = "secret";
 //!     let counter = 0;
 //!     // Get a HOTP instance with a '&str' secret
-//!     let hotp_str = HOTP::from_utf8(secret);
-//!     // Get an otp with the given counter and digit count
-//!     let otp_from_str = hotp_str.get_otp(counter, 6);
+//!     let hotp_str = HOTP::default_from_utf8(secret);
+//!     // Get an otp with the given counter
+//!     let otp_from_str = hotp_str.get_otp(counter);
 //!     println!("The otp from hotp_str: {}", otp_from_str);
 //!
 //!     // Alternatively, get a HOTP instance with a '&[u8]' secret
-//!     let hotp_bytes = HOTP::new(secret.as_bytes());
-//!     // Get an otp with the given counter and digit count
-//!     let otp_from_bytes = hotp_bytes.get_otp(counter, 6);
+//!     let hotp_bytes = HOTP::new(secret.as_bytes(), 6);
+//!     // Get an otp with the given counter
+//!     let otp_from_bytes = hotp_bytes.get_otp(counter);
 //!     println!("The otp from hotp_bytes: {}", otp_from_bytes);
 //! }
 //! ```
@@ -41,23 +41,23 @@
 //!         .expect("Error getting time")
 //!         .as_secs();
 //!     // Get a TOTP instance with an '&str' secret and default SHA1 Digest
-//!     let totp_sha1_str = TOTP::from_utf8(secret);
+//!     let totp_sha1_str = TOTP::default_from_utf8(secret);
 //!     // Get an otp with the given counter and elapsed seconds
-//!     let otp_sha1 = totp_sha1_str.get_otp(elapsed_seconds, 8);
+//!     let otp_sha1 = totp_sha1_str.get_otp(elapsed_seconds);
 //!     println!("The otp from totp_sha1_str: {}", otp_sha1);
 //!
 //!     // Alternatively get a TOTP instance with an '&[u8]' secret
 //!     // and different digest (Sha256 or Sha512)
-//!     let totp_sha256_bytes = TOTP::new_with_digest(
+//!     let totp_sha256_bytes = TOTP::new(
 //!         secret.as_bytes(),
-//!         MacDigest::SHA256
+//!         MacDigest::SHA256, // SHA256 algorithm
+//!         8,  // 8 digits
+//!         60  // 60-second interval
 //!     );
 //!     // Get an otp with the given counter, time and other custom params
-//!     let otp_sha256 = totp_sha256_bytes.get_otp_with_custom(
+//!     let otp_sha256 = totp_sha256_bytes.get_otp_with_custom_time_start(
 //!         elapsed_seconds,
-//!         30, // A 60-second time step
 //!         0, // Start time at unix epoch
-//!         6 // 8-digit code
 //!     );
 //!     println!("The otp from totp_sha256_bytes: {}", otp_sha256);
 //! }