From b5c8e34cba5726dfbcc1a1c82a79602b14b7e5df Mon Sep 17 00:00:00 2001 From: MedzikUser Date: Wed, 29 Jun 2022 14:56:25 +0200 Subject: [PATCH] chore(sha): comment code and update sha tests --- src/sha/error.rs | 12 +++++++++++ src/sha/mac.rs | 44 ++++++++++++++++++++++++++++++---------- src/sha/mod.rs | 40 +++++++++++++++++++++++++++++++------ src/sha/sha.rs | 52 +++++++++++++++++++++++------------------------- 4 files changed, 104 insertions(+), 44 deletions(-) create mode 100644 src/sha/error.rs diff --git a/src/sha/error.rs b/src/sha/error.rs new file mode 100644 index 0000000..e9e8f33 --- /dev/null +++ b/src/sha/error.rs @@ -0,0 +1,12 @@ +use thiserror::Error; + +/// Custom error type +#[derive(Debug, Error)] +pub enum Error { + /// Invalid HMAC Key + #[error("invalid key")] + InvalidKey, +} + +/// Alias to a `Resuly` with the cutom [enum@Error]. +pub type Result = std::result::Result; diff --git a/src/sha/mac.rs b/src/sha/mac.rs index 1e03856..953ad7b 100644 --- a/src/sha/mac.rs +++ b/src/sha/mac.rs @@ -1,18 +1,8 @@ use hmac::{Hmac, Mac}; use sha1::Sha1; use sha2::{Sha256, Sha512}; -use thiserror::Error; -/// Custom error type -#[derive(Debug, Error)] -pub enum Error { - /// Invalid HMAC Key - #[error("invalid key")] - InvalidKey, -} - -/// Alias to a `Resuly` with the cutom [Error]. -pub type Result = std::result::Result; +use super::{Error, Result}; /// HMAC hashing algorithms pub enum AlgorithmMac { @@ -25,6 +15,38 @@ pub enum AlgorithmMac { } /// Compute cryptographic hash from bytes (HMAC Sha1, HMAC Sha256, HMAC Sha512). +/// +/// ## Method 1 (recommend) +/// ``` +/// use crypto_utils::sha::{AlgorithmMac, CryptographicMac}; +/// +/// // compute hash +/// let hash_bytes: Vec = CryptographicMac::hash(AlgorithmMac::HmacSHA1, b"secret", b"input").unwrap(); +/// +/// // decode hash to a String +/// let hash: String = hex::encode(hash_bytes); +/// +/// # assert_eq!(hash, "30440f36ddc2809bbd4c8b1f37a6e80d7588c303".to_string()) +/// ``` +/// +/// ## Method 2 +/// ``` +/// use crypto_utils::sha::{AlgorithmMac, CryptographicMac}; +/// +/// // create a new hasher +/// let mut hasher = CryptographicMac::new(AlgorithmMac::HmacSHA1, b"secret").unwrap(); +/// +/// // set value in hasher +/// hasher.update(b"input"); +/// +/// // compute hash +/// let hash_bytes: Vec = hasher.finalize(); +/// +/// // decode hash to a String +/// let hash: String = hex::encode(hash_bytes); +/// +/// # assert_eq!(hash, "30440f36ddc2809bbd4c8b1f37a6e80d7588c303".to_string()) +/// ``` pub enum CryptographicMac { /// HMAC Sha1 hasher HmacSha1(Hmac), diff --git a/src/sha/mod.rs b/src/sha/mod.rs index 678a964..60c4fce 100644 --- a/src/sha/mod.rs +++ b/src/sha/mod.rs @@ -1,21 +1,49 @@ //! Module for creating sha1, sha256 and sha512 hashes. //! +//! ## Sha +//! +//! Example of computing a sha1, sha256 and sha512 hashes: +//! //! ```no_run //! use crypto_utils::sha::{Algorithm, CryptographicHash}; //! -//! // sha1 -//! CryptographicHash::hash(Algorithm::SHA1, b"P@ssw0rd"); +//! // Sha1 +//! let hash: Vec = CryptographicHash::hash(Algorithm::SHA1, b"input"); //! -//! // sha256 -//! CryptographicHash::hash(Algorithm::SHA256, b"P@ssw0rd"); +//! // Sha256 +//! let hash: Vec = CryptographicHash::hash(Algorithm::SHA256, b"input"); //! -//! // sha512 -//! CryptographicHash::hash(Algorithm::SHA512, b"P@ssw0rd"); +//! // Sha512 +//! let hash: Vec = CryptographicHash::hash(Algorithm::SHA512, b"input"); +//! ``` +//! +//! ## HMAC-Sha +//! +//! Read about HMAC in [wikipedia](https://en.wikipedia.org/wiki/HMAC) +//! +//! Example of computing a HMAC hashes (sha1, sha256 and sha512): +//! +//! ```no_run +//! use crypto_utils::sha::{AlgorithmMac, CryptographicMac}; +//! +//! // secret value +//! const SECRET: &[u8] = b"secret"; +//! +//! // HMAC Sha1 +//! let hash: Vec = CryptographicMac::hash(AlgorithmMac::HmacSHA1, SECRET, b"input").unwrap(); +//! +//! // HMAC Sha256 +//! let hash: Vec = CryptographicMac::hash(AlgorithmMac::HmacSHA256, SECRET, b"input").unwrap(); +//! +//! // HMAC Sha512 +//! let hash: Vec = CryptographicMac::hash(AlgorithmMac::HmacSHA512, SECRET, b"input").unwrap(); //! ``` +mod error; mod mac; #[allow(clippy::module_inception)] mod sha; +pub use error::*; pub use mac::*; pub use sha::*; diff --git a/src/sha/sha.rs b/src/sha/sha.rs index b3543aa..42f939a 100644 --- a/src/sha/sha.rs +++ b/src/sha/sha.rs @@ -14,17 +14,17 @@ pub enum Algorithm { /// Compute cryptographic hash from bytes (sha1, sha256, sha512). /// -/// Method 1 +/// Method 1 (recommend) /// ``` /// use crypto_utils::sha::{Algorithm, CryptographicHash}; /// /// // compute hash -/// let hash_bytes = CryptographicHash::hash(Algorithm::SHA1, b"P@ssw0rd"); +/// let hash_bytes: Vec = CryptographicHash::hash(Algorithm::SHA1, b"P@ssw0rd"); /// /// // decode hash to a String -/// let hash = hex::encode(hash_bytes); +/// let hash: String = hex::encode(hash_bytes); /// -/// assert_eq!(hash, "21bd12dc183f740ee76f27b78eb39c8ad972a757".to_string()) +/// # assert_eq!(hash, "21bd12dc183f740ee76f27b78eb39c8ad972a757".to_string()) /// ``` /// /// Method 2 @@ -32,18 +32,18 @@ pub enum Algorithm { /// use crypto_utils::sha::{Algorithm, CryptographicHash}; /// /// // create a new hasher -/// let mut sha1 = CryptographicHash::new(Algorithm::SHA1); +/// let mut hasher = CryptographicHash::new(Algorithm::SHA1); /// /// // set value in hasher -/// sha1.update(b"P@ssw0rd"); +/// hasher.update(b"P@ssw0rd"); /// /// // compute hash -/// let hash_bytes = sha1.finalize(); +/// let hash_bytes: Vec = hasher.finalize(); /// /// // decode hash to a String -/// let hash = hex::encode(hash_bytes); +/// let hash: String = hex::encode(hash_bytes); /// -/// assert_eq!(hash, "21bd12dc183f740ee76f27b78eb39c8ad972a757".to_string()) +/// # assert_eq!(hash, "21bd12dc183f740ee76f27b78eb39c8ad972a757".to_string()) /// ``` #[derive(Debug, Clone)] pub enum CryptographicHash { @@ -56,7 +56,7 @@ pub enum CryptographicHash { } impl CryptographicHash { - /// Create a new SHA hasher + /// Create a new Sha hasher /// /// ```no_run /// use crypto_utils::sha::{Algorithm, CryptographicHash}; @@ -152,53 +152,51 @@ impl CryptographicHash { mod tests { use super::{Algorithm, CryptographicHash}; + const INPUT: &[u8] = b"input"; + + // expected hashes + const EXPECTED_SHA1: &str = "140f86aae51ab9e1cda9b4254fe98a74eb54c1a1"; + const EXPECTED_SHA256: &str = + "c96c6d5be8d08a12e7b5cdc1b207fa6b2430974c86803d8891675e76fd992c20"; + const EXPECTED_SHA512: &str = + "dc6d6c30f2be9c976d6318c9a534d85e9a1c3f3608321a04b4678ef408124d45d7164f3e562e68c6c0b6c077340a785824017032fddfa924f4cf400e6cbb6adc"; + /// Test a Sha1 hasher #[test] fn sha1() { - // expected hash - let expected_hash = "7726bd9560e1ad4a1a4f056cae5c0c9ea8bacfc2".to_string(); - // compute hash - let hash_bytes = CryptographicHash::hash(Algorithm::SHA1, b"test sha1 hash"); + let hash_bytes = CryptographicHash::hash(Algorithm::SHA1, INPUT); // decode hash to a String let hash = hex::encode(hash_bytes); // validate hash - assert_eq!(hash, expected_hash) + assert_eq!(hash, EXPECTED_SHA1.to_string()) } /// Test a Sha256 hasher #[test] fn sha256() { - // expected hash - let expected_hash = - "eaf6e4198f39ccd63bc3e957d43bf4ef67f12c318c8e3cdc2567a37339902dac".to_string(); - // compute hash - let hash_bytes = CryptographicHash::hash(Algorithm::SHA256, b"test sha256 hash"); + let hash_bytes = CryptographicHash::hash(Algorithm::SHA256, INPUT); // decode hash to a String let hash = hex::encode(hash_bytes); // validate hash - assert_eq!(hash, expected_hash) + assert_eq!(hash, EXPECTED_SHA256.to_string()) } /// Test a Sha512 hasher #[test] fn sha512() { - // expected hash - let expected_hash = - "b43b4d7178014c92f55be828d66c9f98211fc67b385f7790a5b4b2fcb89fe1831645b5a4c17f3f7f11d8f34d2800a77a2b8faa5a0fb9d6b8f7befbc29a9ce795".to_string(); - // compute hash - let hash_bytes = CryptographicHash::hash(Algorithm::SHA512, b"test sha512 hash"); + let hash_bytes = CryptographicHash::hash(Algorithm::SHA512, INPUT); // decode hash to a String let hash = hex::encode(hash_bytes); // validate hash - assert_eq!(hash, expected_hash) + assert_eq!(hash, EXPECTED_SHA512.to_string()) } }