Merge pull request #5 from tmthecoder/add-otp-struct

Add a shared `OTPResult` struct

Author: tmthecoder

src/hotp.rs

@@ -1,5 +1,6 @@
 // Implementation of the HOTP standard according to RFC4226 by Tejas Mehta
 
+use crate::otp_result::OTPResult;
 use crate::util::{base32_decode, get_code, hash_generic, MacDigest};
 
 /// A HOTP Generator
@@ -101,13 +102,14 @@ impl HOTP {
     ///
     /// # Panics
     /// This method panics if the hash's secret is incorrectly given.
-    pub fn get_otp(&self, counter: u64) -> u32 {
+    pub fn get_otp(&self, counter: u64) -> OTPResult {
         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, self.digits)
+        let code = get_code(bytes, self.digits);
+        OTPResult::new(self.digits, code)
     }
 }

src/lib.rs

@@ -80,3 +80,4 @@
 pub mod hotp;
 pub mod totp;
 pub mod util;
+pub mod otp_result;

src/otp_result.rs

@@ -0,0 +1,64 @@
+use std::fmt;
+use std::fmt::Formatter;
+
+/// A convenience struct to hold the result of a [`HOTP`] or [`TOTP`]
+/// generation.
+///
+/// Contains the amount of digits the OTP should be, and the actual OTP,
+/// which will be equal to or less than the digit count. Currently houses
+/// a convenience [`OTPResult::as_string`] which returns a zero-padded string
+/// that has a length of [`OTPResult::digits`]. Additionally, the numerical
+/// representation of the code can be got with [`OTPResult::as_u32`].
+///
+/// Returned as a result of either [`HOTP::get_otp`], [`TOTP::get_otp`]
+/// or [`TOTP::get_otp_with_custom_time_start`].
+#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
+pub struct OTPResult {
+    digits: u32,
+    code: u32,
+}
+
+/// Constructors for the [`OTPResult`] struct.
+impl OTPResult {
+    /// Creates a new instance with the provided digit count and OTP code.
+    pub fn new(digits: u32, code: u32 ) -> Self {
+        OTPResult { digits, code }
+    }
+}
+
+/// Getters for the [`OTPResult`] struct.
+impl OTPResult {
+    /// Gets the digit count given to the struct on creation.
+    ///
+    /// Also the count used to determine how long the formatted string will be.
+    pub fn get_digits(&self) -> u32 { self.digits }
+}
+
+/// Convenience code getters for the [`OTPResult`] struct
+impl OTPResult {
+    /// Returns the OTP as a formatted string of length [`OTPResult.digits`].
+    ///
+    /// If [`OTPResult::code`] is less than [`OTPResult::digits`] long, leading zeroes
+    /// will be added to the string.
+    pub fn as_string(&self) -> String {
+        format!("{:01$}", self.code as usize, self.digits as usize)
+    }
+
+
+    /// Returns the OTP as it's original numerical representation
+    ///
+    /// This number may not be [`OTPResult::digits`] long.
+    pub fn as_u32(&self) -> u32 {
+        self.code
+    }
+}
+
+/// A Display implementation for the [`OTPResult`] struct
+///
+/// Returns the String-formatted code, which is zero-padded
+/// to be [`OTPResult::digits`] long.
+impl fmt::Display for OTPResult {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+       write!(f, "{}", self.as_string())
+    }
+}

src/totp.rs

@@ -1,3 +1,4 @@
+use crate::otp_result::OTPResult;
 use crate::util::{base32_decode, get_code, hash_generic, MacDigest};
 
 /// A TOTP generator
@@ -130,7 +131,7 @@ impl TOTP {
     }
 }
 
-// All getters
+/// All getters for the [`TOTP`] struct
 impl TOTP {
     /// Gets the algorithm used for code generation.
     pub fn get_digest(&self) -> MacDigest {
@@ -148,7 +149,7 @@ impl TOTP {
     }
 }
 
-// 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 specified time.
     ///
@@ -158,7 +159,7 @@ impl TOTP {
     /// # Panics
     /// This method panics if the [`TOTP::get_otp_with_custom_time_start`]
     /// method does, which happens if the hash's secret is incorrectly given.
-    pub fn get_otp(&self, time: u64) -> u32 {
+    pub fn get_otp(&self, time: u64) -> OTPResult {
         self.get_otp_with_custom_time_start(time, 0)
     }
 
@@ -171,7 +172,7 @@ impl TOTP {
     ///
     /// # Panics
     /// This method panics if the hash's secret is incorrectly given.
-    pub fn get_otp_with_custom_time_start(&self, time: u64, time_start: u64) -> u32 {
+    pub fn get_otp_with_custom_time_start(&self, time: u64, time_start: u64) -> OTPResult {
         let time_count = (time - time_start) / self.period;
 
         let hash = hash_generic(&time_count.to_be_bytes(), &self.secret, &self.mac_digest);
@@ -180,6 +181,8 @@ impl TOTP {
             .try_into()
             .expect("Failed byte get");
 
-        get_code(bytes, self.digits)
+
+        let code = get_code(bytes, self.digits);
+        OTPResult::new(self.digits, code)
     }
 }

tests/hotp.rs

@@ -8,21 +8,21 @@ static SECRET_BASE32: &str = "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ";
 /// the Secret Key as a byte array
 fn run_rfc_test_bytes(count: u64) -> u32 {
     let hotp = HOTP::new(SECRET_BYTES, 6);
-    hotp.get_otp(count)
+    hotp.get_otp(count).as_u32()
 }
 
 /// Generic test method to get the HOTP code with
 /// the Secret Key as a string literal
 fn run_rfc_test_utf8(count: u64) -> u32 {
     let hotp = HOTP::default_from_utf8(SECRET_UTF8);
-    hotp.get_otp(count)
+    hotp.get_otp(count).as_u32()
 }
 
 /// Generic test method to get the HOTP code with
 /// the Secret Key as a base32-encoded string
 fn run_rfc_test_base32(count: u64) -> u32 {
     let hotp = HOTP::default_from_base32(SECRET_BASE32);
-    hotp.get_otp(count)
+    hotp.get_otp(count).as_u32()
 }
 
 // All RFC4226 Test Cases (All SHA1)

tests/otp_result.rs

@@ -0,0 +1,15 @@
+use xotp::otp_result::OTPResult;
+
+// Tests whether a code with less than 6 digits adds on leading zeroes
+#[test]
+fn test_padding_needed() {
+    let result = OTPResult::new(6, 1234);
+    assert_eq!("001234", result.as_string())
+}
+
+// Tests whether the formatter will leave the code string as-is
+#[test]
+fn test_padding_not_needed() {
+    let result = OTPResult::new(6, 123456);
+    assert_eq!("123456", result.as_string())
+}

tests/totp.rs

@@ -25,7 +25,7 @@ static SECRET_BASE32_SHA512: &str = "GEZDGNBVGY3TQOJQGEZ\
 /// the SHA1 Secret Key as a byte array
 fn run_rfc_test_bytes(time: u64) -> u32 {
     let totp = TOTP::new(SECRET_BYTES_SHA1, MacDigest::SHA1, 8, 30);
-    totp.get_otp(time)
+    totp.get_otp(time).as_u32()
 }
 
 /// Generic test method to get the TOTP code with
@@ -37,14 +37,14 @@ fn run_rfc_test_bytes_with_digest(time: u64, digest: MacDigest) -> u32 {
         SECRET_BYTES_SHA512
     };
     let totp = TOTP::new(secret, digest, 8, 30);
-    totp.get_otp(time)
+    totp.get_otp(time).as_u32()
 }
 
 /// Generic test method to get the TOTP code with
 /// the SHA1 Secret Key as a string literal
 fn run_rfc_test_utf8(time: u64) -> u32 {
     let totp = TOTP::new_from_utf8(SECRET_UTF8_SHA1, MacDigest::SHA1, 8, 30);
-    totp.get_otp(time)
+    totp.get_otp(time).as_u32()
 }
 
 /// Generic test method to get the TOTP code with
@@ -56,14 +56,14 @@ fn run_rfc_test_utf8_with_digest(time: u64, digest: MacDigest) -> u32 {
         SECRET_UTF8_SHA512
     };
     let totp = TOTP::new_from_utf8(secret, digest, 8, 30);
-    totp.get_otp(time)
+    totp.get_otp(time).as_u32()
 }
 
 /// Generic test method to get the TOTP code with
 /// the SHA1 Secret Key as a base32-encoded string
 fn run_rfc_test_base32(time: u64) -> u32 {
     let totp = TOTP::new_from_base32(SECRET_BASE32_SHA1, MacDigest::SHA1, 8, 30);
-    totp.get_otp(time)
+    totp.get_otp(time).as_u32()
 }
 
 /// Generic test method to get the TOTP code with
@@ -75,7 +75,7 @@ fn run_rfc_test_base32_with_digest(time: u64, digest: MacDigest) -> u32 {
         SECRET_BASE32_SHA512
     };
     let totp = TOTP::new_from_base32(secret, digest, 8, 30);
-    totp.get_otp(time)
+    totp.get_otp(time).as_u32()
 }
 
 // All SHA-1 Tests for TOTP from rfc6238