Merge pull request #19 from GiacomoPope/sha_kat

README.md

@@ -21,17 +21,20 @@ pip install xoflib
 
 We currently have pyO3 bindings for the four Shake XOF available in the [`sha3`](https://crates.io/crates/sha3) crate as well as the Ascon XOFs from the [`ascon-hash`](https://crates.io/crates/ascon-hash) crate.
 
+### Ascon
+
+- [AsconXof()](https://xoflib.readthedocs.io/en/stable/xoflib.html#xoflib.AsconXof)
+- [AsconAXof()](https://xoflib.readthedocs.io/en/stable/xoflib.html#xoflib.AsconAXof)
+
 ### Sha3
 
 - [Shake128()](https://xoflib.readthedocs.io/en/stable/xoflib.html#xoflib.Shake128)
 - [Shake256()](https://xoflib.readthedocs.io/en/stable/xoflib.html#xoflib.Shake256)
-- [TurboShake128()](https://xoflib.readthedocs.io/en/stable/xoflib.html#xoflib.TurboShake128)
-- [TurboShake256()](https://xoflib.readthedocs.io/en/stable/xoflib.html#xoflib.TurboShake256)
 
-### Ascon
+### TurboShake
 
-- [AsconXof()](https://xoflib.readthedocs.io/en/stable/xoflib.html#xoflib.AsconXof)
-- [AsconAXof()](https://xoflib.readthedocs.io/en/stable/xoflib.html#xoflib.AsconAXof)
+- [TurboShake128()](https://xoflib.readthedocs.io/en/stable/xoflib.html#xoflib.TurboShake128)
+- [TurboShake256()](https://xoflib.readthedocs.io/en/stable/xoflib.html#xoflib.TurboShake256)
 
 ### Documentation
 
@@ -93,14 +96,20 @@ The purpose of this package is to implement XOF for their intended use case, wit
 
 ## Tests
 
-### Sha3
+### Ascon
 
-We rely on the testing of the `sha3` crate for correctness of the Shake implementations. For API testing and consistency with `hashlib` we include some unittests for the XOFs exposed in our module: [tests/test_shake.py](https://github.com/GiacomoPope/xoflib/blob/main/tests/test_shake.py)
+`AsconXOF` and `AsconAXof` are tested by comparing the output with the KAT vectors generated from [`pyascon`](https://github.com/meichlseder/pyascon). For more information, see the test file: [tests/test_ascon.py](https://github.com/GiacomoPope/xoflib/blob/main/tests/test_ascon.py)
 
-### Ascon
+### Sha3
+
+`Shake128` and `Shake256` are tested by comparing the output with the KAT vectors downloaded from the "SHA-3 XOF Test Vectors for Byte-Oriented Output" section from [Cryptographic Algorithm Validation Program (CAVP)](https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program/secure-hashing). For more information, see the test file: [tests/test_shake.py](https://github.com/GiacomoPope/xoflib/blob/main/tests/test_shake.py).
 
-`AsconXOF` and `AsconAXof` are both tested by comparing the output with the KAT vectors generated from [`pyascon`](https://github.com/meichlseder/pyascon). For more information, see the test file: [tests/test_ascon.py](https://github.com/GiacomoPope/xoflib/blob/main/tests/test_ascon.py)
+### TurboShake
 
+`TurboShake128` and `TurboShake256` are tested by comparing the output with
+the IRTF CRFG examples [draft-irtf-cfrg-kangarootwelve-14](https://datatracker.ietf.org/doc/draft-irtf-cfrg-kangarootwelve/) from Section 5.
+For more information, see the test file:
+[tests/test_shake.py](https://github.com/GiacomoPope/xoflib/blob/main/tests/test_shake.py).
 
 ## Rough Benchmarking
 

benchmarks/shake_wrapper.py

@@ -1,28 +1,32 @@
 from hashlib import shake_128, shake_256
 
+
 class ShakeStream:
-	"""	
-	Written by David Buchanan
-	
+    """
+        Written by David Buchanan
+
     Taken from:
-	https://github.com/pyca/cryptography/issues/9185#issuecomment-1868518432
-	"""
-	def __init__(self, digestfn) -> None:
-		# digestfn is anything we can call repeatedly with different lengths
-		self.digest = digestfn
-		self.buf = self.digest(32) # arbitrary starting length
-		self.offset = 0
-
-	def read(self, n: int) -> bytes:
-		# double the buffer size until we have enough
-		while self.offset + n > len(self.buf):
-			self.buf = self.digest(len(self.buf) * 2)
-		res = self.buf[self.offset:self.offset + n]
-		self.offset += n
-		return res
-
+        https://github.com/pyca/cryptography/issues/9185#issuecomment-1868518432
+    """
+
+    def __init__(self, digestfn) -> None:
+        # digestfn is anything we can call repeatedly with different lengths
+        self.digest = digestfn
+        self.buf = self.digest(32)  # arbitrary starting length
+        self.offset = 0
+
+    def read(self, n: int) -> bytes:
+        # double the buffer size until we have enough
+        while self.offset + n > len(self.buf):
+            self.buf = self.digest(len(self.buf) * 2)
+        res = self.buf[self.offset : self.offset + n]
+        self.offset += n
+        return res
+
+
 def shake_128_hashlib(absorb):
-	return ShakeStream(shake_128(absorb).digest)
+    return ShakeStream(shake_128(absorb).digest)
+
 
 def shake_256_hashlib(absorb):
-	return ShakeStream(shake_256(absorb).digest)
+    return ShakeStream(shake_256(absorb).digest)

docs/conf.py

@@ -13,10 +13,10 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'xoflib'
-copyright = '2024, Robin Jadoul, Sam Leonard, Giacomo Pope'
-author = 'Robin Jadoul, Sam Leonard, Giacomo Pope'
-release = '0.2.0'
+project = "xoflib"
+copyright = "2024, Robin Jadoul, Sam Leonard, Giacomo Pope"
+author = "Robin Jadoul, Sam Leonard, Giacomo Pope"
+release = "0.2.0"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -25,11 +25,11 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
-    "myst_parser"
+    "myst_parser",
 ]
 
 templates_path = ["_templates"]
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -39,15 +39,15 @@
 intersphinx_mapping = {"Python": ("https://docs.python.org/", None)}
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'lightbulb'
+pygments_style = "lightbulb"
 
 # These folders are copied to the documentation's HTML output
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
 # These paths are either relative to html_static_path
 # or fully qualified paths (eg. https://...)
 html_css_files = [
-    'css/custom.css',
+    "css/custom.css",
 ]
 
 autodoc_default_options = {