From 4118c712ea27e35b41b10fc06e03f38eabc93fce Mon Sep 17 00:00:00 2001 From: omibo Date: Mon, 4 Mar 2024 20:34:35 -0700 Subject: [PATCH 1/9] Document pub struct Message --- .gitignore | 2 ++ src/lib.rs | 18 ++++++++++++++++-- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 81cf465..2d4291b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,4 @@ /target /.vscode + +.DS_Store \ No newline at end of file diff --git a/src/lib.rs b/src/lib.rs index d59ef96..ef84b08 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -2,10 +2,16 @@ /// Elliptic curve backend use tiny_ed448_goldilocks::curve::{extended_edwards::ExtendedPoint, field::scalar::Scalar}; -/// Module for sha3 primitives. +/// Module for SHA-3 primitives pub mod sha3 { + + // Submodule that implements NIST 800-185 compliant functions pub mod aux_functions; + + // Submodule that implements the Keccak-f[1600] permutation pub mod keccakf; + + // Submodule that implements the sponge construction pub mod sponge; } @@ -61,18 +67,26 @@ pub struct KeyPair { } #[derive(Debug)] -/// Message type for which cryptographic traits are defined. +/// Message struct for which cryptographic traits are defined. pub struct Message { + // Input message pub msg: Box>, + // The digest lengths in FIPS-approved hash functions pub d: Option, + // Nonce used in symmetric encryption pub sym_nonce: Option>, + // Nonce used in asymmetric encryption pub asym_nonce: Option, + // Hash value (also known as message digest) pub digest: Result, OperationError>, + // Result of the cryptographic trait pub op_result: Result<(), OperationError>, + // Schnorr signatures on the input message pub sig: Option, } impl Message { + pub fn new(data: Vec) -> Message { Message { msg: Box::new(data), From 959e774999d6a823f2bddc6591a142c703eb88ff Mon Sep 17 00:00:00 2001 From: omibo Date: Mon, 4 Mar 2024 20:45:26 -0700 Subject: [PATCH 2/9] Document pub enum SecParam --- src/lib.rs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index e2099e1..f703832 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -87,6 +87,7 @@ pub struct Message { impl Message { + // Returns a new Message instance pub fn new(data: Vec) -> Message { Message { msg: Box::new(data), @@ -106,10 +107,15 @@ impl Message { // } // } #[derive(Debug, Clone, Copy)] +/// An enum representing standard digest lengths based on FIPS PUB 202 pub enum SecParam { + /// Digest length of 224 bits, also known as SHA3-224 D224 = 224, + /// Digest length of 256 bits, also known as SHA3-256 D256 = 256, + /// Digest length of 384 bits, also known as SHA3-384 D384 = 384, + /// Digest length of 512 bits, also known as SHA3-512 D512 = 512, } From 3a32ba0a294a942ec9610c7883b7e1d1c6dd6abc Mon Sep 17 00:00:00 2001 From: omibo Date: Mon, 4 Mar 2024 21:16:29 -0700 Subject: [PATCH 3/9] Document pub(crate) enum Capacity --- src/lib.rs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index f703832..9fbca3c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -137,10 +137,16 @@ impl SecParam { } #[derive(Debug, Clone, Copy)] +/// An enum representing standard capacity valuess based on FIPS PUB 202. +/// (The capacity of a sponge function) = 2 * (digest length) pub(crate) enum Capacity { + // 2 * SecParam.D224 C448 = 448, + // 2 * SecParam.D256 C512 = 512, + // 2 * SecParam.D384 C768 = 768, + // 2 * SecParam.D512 C1024 = 1024, } From 18bc75f17d0366e417bd9ee7ad0c8a1d328c534a Mon Sep 17 00:00:00 2001 From: omibo Date: Mon, 4 Mar 2024 21:26:00 -0700 Subject: [PATCH 4/9] Document pub struct Rate and OutputLength --- src/lib.rs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index 9fbca3c..9a9c02b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -151,6 +151,7 @@ pub(crate) enum Capacity { } impl Capacity { + /// This function effectively maps a given bit length to the appropriate capacity value enum variant, fn from_bit_length(bit_length: u64) -> Self { match bit_length * 2 { x if x <= 448 => Capacity::C448, @@ -161,6 +162,7 @@ impl Capacity { } } +/// OutputLength struct for storing the output length. pub struct OutputLength { value: u64, } @@ -181,11 +183,14 @@ impl OutputLength { } } +/// Rate struct for storing the rate value. +/// Rate is the number of input bits processed per invocation of the underlying function in sponge construction. pub struct Rate { value: u64, } impl Rate { + // Rate = (Permutation width) - (Capacity) pub fn from(sec_param: &R) -> Self { Rate { value: (1600 - sec_param.bit_length()), From a582b75262df6661fe4aa7397728eaefa24124d7 Mon Sep 17 00:00:00 2001 From: omibo Date: Mon, 4 Mar 2024 21:40:07 -0700 Subject: [PATCH 5/9] Document fn compute_hash_sha3 --- src/lib.rs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index 9a9c02b..5985421 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -238,6 +238,11 @@ pub trait BitLength { } pub trait Hashable { + /// # Message Digest + /// Computes SHA3-d hash of input. + /// ## Arguments: + /// * `d: u64`: requested security strength in bits. Supported + /// bitstrengths are 224, 256, 384, or 512. fn compute_hash_sha3(&mut self, d: &SecParam) -> Result<(), OperationError>; fn compute_tagged_hash(&mut self, pw: &[u8], s: &str, d: &SecParam); } From c6f14e3504e9f43a2b6ab97113b6f4bf6fd0589e Mon Sep 17 00:00:00 2001 From: omibo Date: Mon, 4 Mar 2024 21:41:57 -0700 Subject: [PATCH 6/9] Documented hash-related code in lib.rs --- src/lib.rs | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 5985421..dd9e3ed 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -86,7 +86,6 @@ pub struct Message { } impl Message { - // Returns a new Message instance pub fn new(data: Vec) -> Message { Message { @@ -137,7 +136,7 @@ impl SecParam { } #[derive(Debug, Clone, Copy)] -/// An enum representing standard capacity valuess based on FIPS PUB 202. +/// An enum representing standard capacity valuess based on FIPS PUB 202. /// (The capacity of a sponge function) = 2 * (digest length) pub(crate) enum Capacity { // 2 * SecParam.D224 @@ -151,7 +150,7 @@ pub(crate) enum Capacity { } impl Capacity { - /// This function effectively maps a given bit length to the appropriate capacity value enum variant, + /// This function effectively maps a given bit length to the appropriate capacity value enum variant, fn from_bit_length(bit_length: u64) -> Self { match bit_length * 2 { x if x <= 448 => Capacity::C448, @@ -183,8 +182,8 @@ impl OutputLength { } } -/// Rate struct for storing the rate value. -/// Rate is the number of input bits processed per invocation of the underlying function in sponge construction. +/// Rate struct for storing the rate value. +/// Rate is the number of input bits processed per invocation of the underlying function in sponge construction. pub struct Rate { value: u64, } @@ -239,7 +238,7 @@ pub trait BitLength { pub trait Hashable { /// # Message Digest - /// Computes SHA3-d hash of input. + /// Computes SHA3-d hash of input. /// ## Arguments: /// * `d: u64`: requested security strength in bits. Supported /// bitstrengths are 224, 256, 384, or 512. From 576d4457921d06d74aa51c6446b6136e2410eef5 Mon Sep 17 00:00:00 2001 From: omibo Date: Tue, 5 Mar 2024 18:36:15 -0700 Subject: [PATCH 7/9] Convert // to /// --- .gitignore | 4 +--- src/lib.rs | 31 +++++++++++++------------------ 2 files changed, 14 insertions(+), 21 deletions(-) diff --git a/.gitignore b/.gitignore index 2d4291b..0f84cc9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,2 @@ /target -/.vscode - -.DS_Store \ No newline at end of file +/.vscode \ No newline at end of file diff --git a/src/lib.rs b/src/lib.rs index dd9e3ed..5c2c89b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -69,24 +69,24 @@ pub struct KeyPair { #[derive(Debug)] /// Message struct for which cryptographic traits are defined. pub struct Message { - // Input message + /// Input message pub msg: Box>, - // The digest lengths in FIPS-approved hash functions + /// The digest lengths in FIPS-approved hash functions pub d: Option, - // Nonce used in symmetric encryption + /// Nonce used in symmetric encryption pub sym_nonce: Option>, - // Nonce used in asymmetric encryption + /// Nonce used in asymmetric encryption pub asym_nonce: Option, - // Hash value (also known as message digest) + /// Hash value (also known as message digest) pub digest: Result, OperationError>, - // Result of the cryptographic trait + /// Result of the cryptographic trait pub op_result: Result<(), OperationError>, - // Schnorr signatures on the input message + /// Schnorr signatures on the input message pub sig: Option, } impl Message { - // Returns a new Message instance + /// Returns a new Message instance pub fn new(data: Vec) -> Message { Message { msg: Box::new(data), @@ -139,13 +139,13 @@ impl SecParam { /// An enum representing standard capacity valuess based on FIPS PUB 202. /// (The capacity of a sponge function) = 2 * (digest length) pub(crate) enum Capacity { - // 2 * SecParam.D224 + /// 2 * SecParam.D224 C448 = 448, - // 2 * SecParam.D256 + /// 2 * SecParam.D256 C512 = 512, - // 2 * SecParam.D384 + /// 2 * SecParam.D384 C768 = 768, - // 2 * SecParam.D512 + /// 2 * SecParam.D512 C1024 = 1024, } @@ -189,7 +189,7 @@ pub struct Rate { } impl Rate { - // Rate = (Permutation width) - (Capacity) + /// Rate = (Permutation width) - (Capacity) pub fn from(sec_param: &R) -> Self { Rate { value: (1600 - sec_param.bit_length()), @@ -237,11 +237,6 @@ pub trait BitLength { } pub trait Hashable { - /// # Message Digest - /// Computes SHA3-d hash of input. - /// ## Arguments: - /// * `d: u64`: requested security strength in bits. Supported - /// bitstrengths are 224, 256, 384, or 512. fn compute_hash_sha3(&mut self, d: &SecParam) -> Result<(), OperationError>; fn compute_tagged_hash(&mut self, pw: &[u8], s: &str, d: &SecParam); } From 846569b6708c9d5b01016d99c13daf0e08e71818 Mon Sep 17 00:00:00 2001 From: Dustin Ray <40841027+drcapybara@users.noreply.github.com> Date: Tue, 5 Mar 2024 19:16:15 -0800 Subject: [PATCH 8/9] Update lib.rs --- src/lib.rs | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 5c2c89b..c677860 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -5,13 +5,13 @@ use tiny_ed448_goldilocks::curve::{extended_edwards::ExtendedPoint, field::scala /// Module for SHA-3 primitives pub mod sha3 { - // Submodule that implements NIST 800-185 compliant functions + /// Submodule that implements NIST 800-185 compliant functions pub mod aux_functions; - // Submodule that implements the Keccak-f[1600] permutation + /// Submodule that implements the Keccak-f[1600] permutation pub mod keccakf; - // Submodule that implements the sponge construction + /// Submodule that implements the sponge construction pub mod sponge; } @@ -100,11 +100,6 @@ impl Message { } } -// impl PartialEq for Message { -// fn eq(&self, other: &self) -> bool { -// self.msg == other.msg; -// } -// } #[derive(Debug, Clone, Copy)] /// An enum representing standard digest lengths based on FIPS PUB 202 pub enum SecParam { From db16802b21bfb33ca5b5abe1eda223fc97fb607e Mon Sep 17 00:00:00 2001 From: Dustin Ray <40841027+drcapybara@users.noreply.github.com> Date: Tue, 5 Mar 2024 19:16:27 -0800 Subject: [PATCH 9/9] Update .gitignore --- .gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 0f84cc9..81cf465 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,2 @@ /target -/.vscode \ No newline at end of file +/.vscode