rusotp 0.5.0

Rust implementation of the HOTP and TOTP algorithms
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

// Copyright (c) Indrajit Roy
//
// This file is licensed under the Affero General Public License version 3 or
// any later version.
//
// See the file LICENSE for details.

use hmac::Mac;
use sha1::Sha1;
use sha2::{Sha256, Sha512};

/// Trait for defining common behavior for different hashing algorithms.
///
/// # Methods
///
/// * `to_string` - Converts the algorithm to its string representation.
/// * `from_string` - Creates an algorithm instance from its string representation.
/// * `hash` - Hashes the given secret and data using the algorithm.
///
/// # Errors
///
/// The `hash` method returns an error if the hashing process fails.
pub trait AlgorithmTrait {
    fn to_string(&self) -> String;
    fn from_string(s: String) -> Option<Self>
    where
        Self: Sized;
    fn hash(&self, secret: Vec<u8>, data: u64) -> Result<Vec<u8>, String>;
}

/// Enum representing the supported hashing algorithms.
///
/// # Variants
///
/// * `SHA1` - Represents the SHA-1 hashing algorithm.
/// * `SHA256` - Represents the SHA-256 hashing algorithm.
/// * `SHA512` - Represents the SHA-512 hashing algorithm.
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub enum Algorithm {
    SHA1,
    SHA256,
    SHA512,
}

impl AlgorithmTrait for Algorithm {
    /// Converts the algorithm to its string representation.
    ///
    /// # Returns
    ///
    /// A `String` representing the algorithm name.
    ///
    /// # Example
    ///
    /// ```rust
    /// use rusotp::{Algorithm, AlgorithmTrait};
    ///
    /// let algo = Algorithm::SHA256;
    /// ```
    fn to_string(&self) -> String {
        match self {
            Algorithm::SHA1 => "SHA1".into(),
            Algorithm::SHA256 => "SHA256".into(),
            Algorithm::SHA512 => "SHA512".into(),
        }
    }

    /// Creates an `Algorithm` instance from its string representation.
    ///
    /// # Arguments
    ///
    /// * `name` - A `String` representing the algorithm name (e\.g\., `"SHA1"`, `"SHA256"`, or `"SHA512"`)\.
    ///
    /// # Returns
    ///
    /// An `Option<Algorithm>` corresponding to the string\. Returns `None` if the string does not match any supported algorithm\.
    ///
    /// # Example
    ///
    /// ```rust
    /// use rusotp::{Algorithm, AlgorithmTrait};
    ///
    /// let algo = Algorithm::from_string("SHA256".to_string());
    /// assert_eq!(algo, Some(Algorithm::SHA256));
    /// ```
    fn from_string(name: String) -> Option<Self> {
        match name.as_str() {
            "SHA1" => Some(Algorithm::SHA1),
            "SHA256" => Some(Algorithm::SHA256),
            "SHA512" => Some(Algorithm::SHA512),
            _ => None,
        }
    }

    /// Hashes the given secret and data using the selected algorithm.
    ///
    /// # Arguments
    ///
    /// * `secret` - A `Vec<u8>` representing the shared secret key.
    /// * `data` - A `u64` value representing the data to be hashed.
    ///
    /// # Returns
    ///
    /// A `Result` containing a `Vec<u8>` with the hashed value if successful, or a `String` with the error message if the hashing process fails.
    ///
    /// # Errors
    ///
    /// Returns an error if the HMAC construction or finalization fails.
    ///
    /// # Example
    ///
    /// ```
    /// use rusotp::{Algorithm, AlgorithmTrait};
    ///
    /// let secret = vec![1, 2, 3, 4, 5, 6, 7, 8];
    /// let data = 123456u64;
    /// let algo = Algorithm::SHA256;
    /// let result = algo.hash(secret, data);
    /// assert!(result.is_ok());
    /// ```
    fn hash(&self, secret: Vec<u8>, data: u64) -> Result<Vec<u8>, String> {
        match self {
            Algorithm::SHA1 => match hmac::Hmac::<Sha1>::new_from_slice(secret.as_ref()) {
                Ok(mut mac) => {
                    mac.update(&data.to_be_bytes());
                    Ok(mac.finalize().into_bytes().to_vec())
                }
                Err(e) => Err(e.to_string()),
            },
            Algorithm::SHA256 => match hmac::Hmac::<Sha256>::new_from_slice(secret.as_ref()) {
                Ok(mut mac) => {
                    mac.update(&data.to_be_bytes());
                    Ok(mac.finalize().into_bytes().to_vec())
                }
                Err(e) => Err(e.to_string()),
            },
            Algorithm::SHA512 => match hmac::Hmac::<Sha512>::new_from_slice(secret.as_ref()) {
                Ok(mut mac) => {
                    mac.update(&data.to_be_bytes());
                    Ok(mac.finalize().into_bytes().to_vec())
                }
                Err(e) => Err(e.to_string()),
            },
        }
    }
}

#[cfg(test)]
mod algorithm_test;