Fix/issue 9 #50

omibo · 2024-02-02T07:21:44Z

Add documentation for keccakf.rs and aux_functions.rs.
Specifically:

keccakf.rs:

rotate_left64() function.
keccakf_1600 function.

aux_functions.rs:

nist_800_185 module
byte_utils module

Dustin-Ray · 2024-02-06T21:32:19Z

src/sha3/aux_functions.rs

    /// The bytepad(X, w) function prepends an encoding of the integer w to an input string X, then pads
-    /// the result with zeros until it is a byte string whose length in bytes is a multiple of w.
-    /// * `x`: the byte string to pad
-    /// * `w`: the rate of the sponge
-    /// * `return`: z = encode(`x`) + `x` + (`0` * LCM of length of z and w)
+    /// the result with zeros until it is a byte string whose length in bytes is a multiple of w. See NIST SP 800-185 2.3.3 .
+    /// # Arguments:
+    /// * `input` - The byte string to pad.
+    /// * `w` - The rate of the sponge.
+    ///
+    /// # Returns:
+    /// A byte string z = encode(x) + x + (0 * LCM of length of z and w)


this isnt necessary right now

Dustin-Ray · 2024-02-06T21:32:26Z

src/sha3/aux_functions.rs

    /// The encode_string function is used to encode bit strings in a way that may be parsed
-    /// unambiguously from the beginning of the string.
-    /// * `return`: left_encode(len(`s`)) + `s`
+    /// unambiguously from the beginning of the string. See NIST SP 800-185 2.3.2 .
+    ///
+    /// # Arguments:
+    /// * `s` - A reference to a vector of bytes.
+    ///
+    /// # Returns:
+    /// A byte string representing the left-encoded length of `s` concatenated with `s`.


this isnt necessary right now

Dustin-Ray · 2024-02-06T21:32:41Z

src/sha3/aux_functions.rs

+    /// # Left Encode
+    /// Encodes the input as a vecotr of bytes in a way that can be unambiguously parsed
+    /// from the beginning of the string by inserting the length of the byte string before the byte string
+    /// representation of the input. See NIST SP 800-185 2.3.1 .
+    /// 
+    /// # Arguments:
+    /// * `value` - The 64-bit unsigned integer to encode.
+    /// 
+    /// # Returns:
+    /// A vector of bytes representing the left-encoded value.


this isnt necessary right now

Dustin-Ray · 2024-02-06T21:34:20Z

src/sha3/aux_functions.rs

+    /// Returns a string representation of the current local date and time.
+    ///
+    /// # Returns:
+    /// A string timestamp representing the current local time and date corresponding to the locale on the local machine.


although the rest of the library follows this pattern in many places, the return is actually implicit and this extra notation adds unneeded verbosity

Dustin-Ray · 2024-02-06T21:34:58Z

src/sha3/aux_functions.rs

+    /// # Right Encode
+    /// Encodes the input as a byte string in a way that can be unambiguously parsed
+    /// from the end of the string by inserting the length of the byte string after the byte string
+    /// representation of the input. See NIST SP 800-185 2.3.1 .
+    /// 
+    /// # Arguments:
+    /// * `value` - The 64-bit unsigned integer to encode.
+    /// 
+    /// # Returns:
+    /// A vector of bytes representing the right-encoded value.


this isnt necessary right now

Dustin-Ray · 2024-02-06T21:35:05Z

src/sha3/aux_functions.rs

+
+    /// Generates and returns a vector of random bytes of the specified size.
+    ///
+    /// # Arguments:
+    /// * `size` - The size of the vector of random bytes to generate.
+    ///
+    /// # Returns:
+    /// A vector of random bytes.


this isnt necessary right now

Dustin-Ray · 2024-02-06T21:35:11Z

src/sha3/aux_functions.rs

+    /// Generates and returns a random big integer with the specified number of bits.
+    ///
+    /// # Arguments:
+    /// * `bits` - The number of bits for the random big integer.
+    ///
+    /// # Returns:
+    /// A random big integer.


this isnt necessary right now

Dustin-Ray · 2024-02-06T21:35:18Z

src/sha3/aux_functions.rs

+    /// Performs in-place XOR operation on two byte streams using iterators.
+    ///
+    /// # Arguments:
+    /// * `a` - A mutable reference to a vector of bytes to be XORed and replaced with the result.
+    /// * `b` - An immutable reference to a vector of bytes.
+    ///
+    /// # Return:
+    /// The result of the XOR operation is stored in the vector referenced by `a`.
+    /// 
+    /// # Remarks:
+    /// This function is a probable bottleneck unless implemented with SIMD.


this isnt necessary right now

Dustin-Ray · 2024-02-06T21:35:53Z

src/sha3/keccakf.rs

+/// # Rotate Left
+/// Rotate a 64-bit unsigned integer to the left by a specified number of bits.
+///
+/// # Arguments:
+/// * `x` - The 64-bit unsigned integer to rotate.
+/// * `y` - The number of bits to rotate `x` by.
+///
+/// # Returns:
+/// The rotated 64-bit unsigned integer.


this isnt necessary right now, particularly because its not pub.

Dustin-Ray · 2024-02-06T21:36:14Z

src/sha3/keccakf.rs

 fn rotate_left64(x: u64, y: u64) -> u64 {
+    // The expression ((x) >> (64 - (y))) effectively adds the y most significant bits of the input x as the least significant bits of the shifted value.


this isnt necessary right now

Dustin-Ray · 2024-02-06T21:38:07Z

thanks for the effort on this. The original objective of #9 is to find anything that is undocumented and provide documentation if it makes sense to do so. Much of this PR is modifying existing docs which isnt really needed at this time.

the area that needs the most help right now would be here, anything that is pub will be publicly exposed and should have docs explaining its usage.

Dustin-Ray · 2024-02-06T21:41:26Z

.DS_Store

this should be added to gitignore and should not be included with a pr

omibo added 2 commits January 31, 2024 20:39

Add documentation for the rotate_left64() and keccakf_1600() functions

5bc46de

Add documentation for nist_800_185 and byte_utils modules

e4dfedb

Dustin-Ray reviewed Feb 6, 2024

View reviewed changes

.DS_Store

Copy link

Owner

Dustin-Ray Feb 6, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this should be added to gitignore and should not be included with a pr

omibo closed this Feb 11, 2024

omibo deleted the fix/issue-9 branch February 11, 2024 03:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix/issue 9 #50

Fix/issue 9 #50

omibo commented Feb 2, 2024

Dustin-Ray Feb 6, 2024

Dustin-Ray Feb 6, 2024

Dustin-Ray Feb 6, 2024

Dustin-Ray Feb 6, 2024

Dustin-Ray Feb 6, 2024

Dustin-Ray Feb 6, 2024

Dustin-Ray Feb 6, 2024

Dustin-Ray Feb 6, 2024

Dustin-Ray Feb 6, 2024

Dustin-Ray Feb 6, 2024

Dustin-Ray commented Feb 6, 2024 •

edited

Loading

Dustin-Ray Feb 6, 2024

		fn rotate_left64(x: u64, y: u64) -> u64 {
		// The expression ((x) >> (64 - (y))) effectively adds the y most significant bits of the input x as the least significant bits of the shifted value.

Fix/issue 9 #50

Fix/issue 9 #50

Conversation

omibo commented Feb 2, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Dustin-Ray commented Feb 6, 2024 • edited Loading

Choose a reason for hiding this comment

Dustin-Ray commented Feb 6, 2024 •

edited

Loading