README details and author listing

LICENSE

@@ -1,7 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Giacomo Pope
-Copyright (c) 2024 Sam Leonard
+Copyright (c) 2024 Robin Jadoul, Sam Leonard, Giacomo Pope
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -4,7 +4,28 @@
 
 # xof-py
 
-## Example
+A Python package for the Shake extendable-output functions (XOFs): Shake128,
+Shake256 and the turbo variants. Built using
+[pyO3](https://github.com/PyO3/pyo3) bindings for the
+[`sha3`](https://docs.rs/sha3/latest/sha3/) crate.
+
+### Motivation
+
+For most hashing needs, the `hashlib` module is appropriate. However, the
+package maintainers have 
+[decided to not support Shake as an XOF](https://github.com/python/cpython/issues/82198) 
+and simply treat it as another hash with digest. This means that if a user reads
+`n` bytes and then wishes for the next `m` bytes of output, they must generate
+`n + m` bytes from a `digest()` call and then slice the output for the last `m`
+bytes.
+
+This can be an issue for cryptographic protocols, such as the post-quantum
+protocols ML-KEM (Kyber) and ML-DSA (Dilithium), which rely on Shake128 and
+Shake256 to continuously read bytes for rejection sampling.
+
+The purpose of this package is to implement XOF for their intended use case, with `absorb()`, `finalize()` and `read()` methods, which allow for the correct instantiation of the XOF as well as efficient sampling of bytes.
+
+## Example Usage
 
 ```py
 >>> from xof import Shaker128
@@ -17,13 +38,13 @@
 
 ## Tests
 
-Could be expanded, currently just check random tests against hashlib
+There is currently partial coverage for testing the bindings in `tests/`. The `sha3` crate which we bind to is thoroughly tested.
 
 ## Documentation
 
 https://xof-py.readthedocs.io/
 
-## Benchmark
+## Rough Benchmark
 
 ```
 10_000 calls with xof library: 0.014042854309082031
@@ -35,3 +56,5 @@ https://xof-py.readthedocs.io/
 100_000 block reads xof library: 0.5895988941192627
 100_000 block reads pycryptodome: 1.635364055633545
 ```
+
+For more information, see the file [`benchmarks/benchmark_xof.py`](benchmarks/benchmark_xof.py).

docs/conf.py

@@ -14,8 +14,8 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'xof-py'
-copyright = '2024, CryptoHack'
-author = 'CryptoHack'
+copyright = '2024, Sam Leonard, Giacomo Pope'
+author = 'Robin Jadoul, Sam Leonard, Giacomo Pope'
 release = '0.1'
 
 # -- General configuration ---------------------------------------------------

docs/index.rst

@@ -10,13 +10,5 @@ Welcome to xof's documentation!
    :maxdepth: 2
    :caption: Contents:
 
-   api
+   xof
 
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

docs/xof.rst

@@ -1,4 +1,4 @@
-xof\_py package
+xof package
 =================
 
 Module contents

src/lib.rs

@@ -155,7 +155,9 @@ impl_sponge_shaker_classes!(
     TurboSponge256
 );
 
-/// A Python module implemented in Rust.
+/// A Python package for the Shake extendable-output functions (XOFs): Shake128,
+/// Shake256 and the turbo variants built with pyO3 bindings to the sha3 Rust
+/// crate.
 #[pymodule]
 fn xof(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<Sponge128>()?;