Update README

CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing
+This library is designed to prototype lattice-based cryptography. Our intent for this library is to be maintained by the community. We encourage anyone to add missing, frequently used features for lattice-based prototyping to this library, and we are happy to help with that process.
+
+More generally, all contributions such as bugfixes, documentation and tests are welcome. Please go ahead and submit your pull requests.
+
+## Choosing the right location
+The qFALL library is divided into three repositories: [qFALL-math](https://github.com/qfall/math), [qFALL-tools](https://github.com/qfall/tools) and [qFALL-schemes](https://github.com/qfall/schemes).
+
+Please add new features to one of these repositories, roughly following these guidelines.
+- If your feature implements a general mathematical function, then add your code to [qFALL-math](https://github.com/qfall/math).
+- If your feature implements a fundamental primitive or shortcut that is commonly used in the construction of lattice-based schemes, e.g., G-trapdoors, then add your code to [qFALL-tools](https://github.com/qfall/tools).
+- If you implement a construction, e.g., Kyber, then add your code to [qFALL-schemes](https://github.com/qfall/schemes).
+
+When in doubt, just submit your pull request to the repository you feel is best suited for your code. We will sort it.
+
+## Style Guide
+Our style guide is based on the [rust standard](https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md). These rules summarise our style guidelines.
+- Every function should be documented. A doc-comment includes a concise description of the function and an example. In case it receives parameters other than `self`, it also includes a description of every parameter, the output type, and behavior. If applicable, it also includes Error and Panic behavior and references to scientific literature.
+- If the code of your function is not self-explanatory from your doc-comment, use inline-comments `//` to briefly describe the steps.
+- A file should always have the copyright notice at the top, followed by a very brief inner doc-comment to summarise the purpose of this file, grouped up imports, implementations of all features, and finally tests of each feature in a separate test-module with a brief doc-comment for each test.
+- Overall, any feature should get a descriptive but concise name s.t. it can be discovered intuitively.
+- Code in our library needs to be formatted using `cargo fmt` and satisfy `clippy`'s standards.
+- We aim for multiple tests per function, its unforeseen behavior, panic or error-cases to boost confidence in our implementations and ensure that modifications of a function only introduce intended changes of behavior.
+- Last but not least, we would like to minimise the number of dependencies of all crates to keep them as slim and quickly compilable as possible.
+
+## Documentation
+The documentation for each crate is available online and it can be generated locally by running the following command in the root directory of this repository.
+```bash
+cargo doc --open
+```
+
+Furthermore, here is an example of a doc-comment of a function that follows our guidelines.
+```rust
+impl Z {
+    /// Chooses a [`Z`] instance according to the discrete Gaussian distribution
+    /// in `[center - ⌈6 * s⌉ , center + ⌊6 * s⌋ ]`.
+    ///
+    /// This function samples discrete Gaussians according to the definition of
+    /// SampleZ in [GPV08](https://citeseerx.ist.psu.edu/document?repid=rep1&type=pdf&doi=d9f54077d568784c786f7b1d030b00493eb3ae35).
+    ///
+    /// Parameters:
+    /// - `n`: specifies the range from which is sampled
+    /// - `center`: specifies the position of the center with peak probability
+    /// - `s`: specifies the Gaussian parameter, which is proportional
+    ///   to the standard deviation `sigma * sqrt(2 * pi) = s`
+    ///
+    /// Returns new [`Z`] sample chosen according to the specified discrete Gaussian
+    /// distribution or a [`MathError`] if the specified parameters were not chosen
+    /// appropriately, i.e. `s < 0`.
+    ///
+    /// # Examples
+    /// ```
+    /// use qfall_math::integer::Z;
+    ///
+    /// let sample = Z::sample_discrete_gauss(0, 1).unwrap();
+    /// ```
+    ///
+    /// # Errors and Failures
+    /// - Returns a [`MathError`] of type [`InvalidIntegerInput`](MathError::InvalidIntegerInput)
+    ///   if `s < 0`.
+    ///
+    /// This function implements SampleZ according to:
+    /// - \[1\] Gentry, Craig and Peikert, Chris and Vaikuntanathan, Vinod (2008).
+    ///   Trapdoors for hard lattices and new cryptographic constructions.
+    ///   In: Proceedings of the fortieth annual ACM symposium on Theory of computing.
+    ///   <https://dl.acm.org/doi/pdf/10.1145/1374376.1374407>
+    pub fn sample_discrete_gauss(center: impl Into<Q>, s: impl Into<Q>) -> Result<Self, MathError> {...}
+}
+```

Cargo.toml

@@ -1,15 +1,23 @@
 [package]
 name = "qfall-tools"
 version = "0.1.0"
-edition = "2021"
+edition = "2024"
+rust-version = "1.85" # due to rand and rand_distr dependency
+description = "Common sub-modules and procedures in lattice-based constructions"
+readme = "README.md"
+homepage = "https://qfall.github.io"
+repository = "https://github.com/qfall/tools"
+license = "MPL-2.0"
+keywords = ["prototype", "lattice", "cryptography"]
+categories = ["cryptography", "mathematics", "development-tools::build-utils", "development-tools::testing", "development-tools::profiling"]
 autobenches = false
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
 qfall-math = { git = "https://github.com/qfall/math", branch = "dev" }
 flint-sys = "0.7.3"
-sha2 = "0.10.6"
+sha2 = "0.10"
 serde = {version="1.0", features=["derive"]}
 serde_json = "1.0"
 typetag = "0.2"

README.md

@@ -1,61 +1,104 @@
 # qFALL-tools
+[<img alt="github" src="https://img.shields.io/badge/qfall--tools-github?style=for-the-badge&logo=github&label=github&color=8da0cb" height="20">](https://github.com/qfall/tools)
+[<img alt="crates.io" src="https://img.shields.io/badge/qfall--tools-cratesio?style=for-the-badge&logo=rust&label=crates&color=fc8d62" height="20">](https://crates.io/crates/qfall-tools)
+[<img alt="docs.rs" src="https://img.shields.io/badge/qfall--tools-docs?style=for-the-badge&logo=docs.rs&label=docs.rs&color=66c2a5" height="20">](https://docs.rs/qfall-tools)
+[<img alt="tutorial" src="https://img.shields.io/badge/book-tutorial?style=for-the-badge&logo=mdBook&label=Tutorial&color=ffd92f" height="20">](https://qfall.github.io/book)
+[<img alt="build" src="https://img.shields.io/github/actions/workflow/status/qfall/tools/push.yml?branch=main&style=for-the-badge" height="20">](https://github.com/qfall/tools/actions/workflows/push.yml)
+[<img alt="license" src="https://img.shields.io/badge/License-MPL_2.0-blue.svg?style=for-the-badge" height="20">](https://github.com/qfall/tools/blob/dev/LICENSE)
 
-[![made-with-rust](https://img.shields.io/badge/Made%20with-Rust-1f425f.svg)](https://www.rust-lang.org/)
-[![CI](https://github.com/qfall/tools/actions/workflows/push.yml/badge.svg?branch=dev)](https://github.com/qfall/tools/actions/workflows/pull_request.yml)
-[![License: MPL 2.0](https://img.shields.io/badge/License-MPL_2.0-brightgreen.svg)](https://opensource.org/licenses/MPL-2.0)
-
-This repository is currently being developed by the project group [qFALL - quantum resistant fast lattice library](https://cs.uni-paderborn.de/cuk/lehre/veranstaltungen/ws-2022-23/project-group-qfall) in the winter term 2022 and summer term 2023 by the Codes and Cryptography research group in Paderborn.
-
-The main objective of this project is to provide researchers and students with the possibility to easily and quickly prototype (lattice-based) cryptography.
-
-## Disclaimer
-
-Currently, we are in the development phase and interfaces might change.
-Feel free to check out the current progress, but be aware, that the content will
-change in the upcoming weeks and months. An official release will most likely be published in the second half of 2023.
+`qFALL` is a prototyping library for lattice-based cryptography.
+This `tools`-crate collects common sub-modules and features used by lattice-based constructions to simplify and accelerate the development of such.
 
 ## Quick-Start
+First, ensure that you use a Unix-like distribution (Linux or MacOS). Setup [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) if you're using Windows. This is required due to this crate's dependency on FLINT.
+Then, make sure your `rustc --version` is `1.85` or newer. 
 
-Please refer to [our website](https://qfall.github.io/) as central information point.
-
-To install and add our library to your project, please refer to [our tutorial](https://qfall.github.io/book/index.html).
-It provides a step-by-step guide to install the required libraries and gives further insights in the usage of our crates.
+Furthermore, it's required that `m4`, a C-compiler such as `gcc`, and `make` are installed.
+```bash
+sudo apt-get install m4 gcc make
+```
+Then, add you can add this crate to your project by executing the following command.
+```bash
+cargo add qfall-tools
+```
+- Find further information on [our website](https://qfall.github.io/). Also check out [`qfall-math`](https://crates.io/crates/qfall-math) and [`qfall-schemes`](https://crates.io/crates/qfall-schemes).
+- Read the [documentation of this crate](https://docs.rs/qfall-tools).
+- We recommend [our tutorial](https://qfall.github.io/book) to start working with qFALL.
 
 ## What does qFALL-tools offer?
+qFALL-tools offers several commonly used sub-modules specific to lattice-based cryptography.
+- [Compression Techniques](https://docs.rs/qfall-tools/latest/qfall_tools/compression/index.html)
+  - [Lossy Compression according to FIPS 203](https://docs.rs/qfall-tools/latest/qfall_tools/compression/trait.LossyCompressionFIPS203.html)
+- [Preimage Samplable Functions (PSF)](https://docs.rs/qfall-tools/latest/qfall_tools/primitive/psf/index.html)
+  - [GPV-based PSF over Z_q](https://docs.rs/qfall-tools/latest/qfall_tools/primitive/psf/struct.PSFGPV.html)
+  - [GPV-based PSF over R_q](https://docs.rs/qfall-tools/latest/qfall_tools/primitive/psf/struct.PSFGPVRing.html)
+  - [MP12 / Perturbation-based PSF over Z_q](https://docs.rs/qfall-tools/latest/qfall_tools/primitive/psf/struct.PSFPerturbation.html)
+- [Trapdoors](https://docs.rs/qfall-tools/latest/qfall_tools/sample/g_trapdoor/index.html)
+  - [G-trapdoor incl. short basis](https://docs.rs/qfall-tools/latest/qfall_tools/sample/g_trapdoor/gadget_classical/index.html)
+  - [Ring-based G-trapdoor incl. short basis](https://docs.rs/qfall-tools/latest/qfall_tools/sample/g_trapdoor/gadget_ring/index.html)
+
+Furthermore, this crate simplifies the implementation of your prototype by supporting a range of [utility functions](https://docs.rs/qfall-tools/latest/qfall_tools/utils/index.html) to quickly instantiate [commonly used moduli](https://docs.rs/qfall-tools/latest/qfall_tools/utils/common_moduli/index.html), [rotation matrices](https://docs.rs/qfall-tools/latest/qfall_tools/utils/rotation_matrix/index.html), and [encodings](https://docs.rs/qfall-tools/latest/qfall_tools/utils/common_encodings/index.html).
+
+## Quick Examples
+From String to Encoding for Encryption
+```rust
+use qfall_tools::utils::{common_moduli::new_anticyclic, common_encodings::encode_value_in_polynomialringzq};
+use qfall_math::integer::Z;
+
+// Create X^256 + 1 mod 3329
+let poly_mod = new_anticyclic(256, 3329).unwrap();
+// Generate integer from string
+let message = Z::from_utf8("Hello!");
+// Turn string into encoding q/2 and 0 for each 1 and 0 bit respectively
+let mu_q_half = encode_value_in_polynomialringzq(message, 2, &poly_mod).unwrap();
+```
 
-qFALL-tools offers a variety of implementations of commonly used tools in lattice-based cryptography.
-We provide a brief overview in the following list.
-For a more detailed description, please refer to [our tutorial section](https://qfall.github.io/book/crypto/features.html).
+Preimage Sampling using a PSF
+```rust
+use qfall_tools::primitive::psf::{PSF, PSFPerturbation};
+use qfall_tools::sample::g_trapdoor::gadget_parameters::GadgetParameters;
+use qfall_math::rational::Q;
+
+let psf = PSFPerturbation {
+    gp: GadgetParameters::init_default(8, 64),
+    r: Q::from(3),
+    s: Q::from(25),
+};
+
+// Generate matrix A with a trapdoor
+let (a, td) = psf.trap_gen();
+// Choose a random target
+let domain_sample = psf.samp_d();
+let target = psf.f_a(&a, &domain_sample);
+// Sample a preimage for the given target
+let preimage = psf.samp_p(&a, &td, &target);
+
+assert!(psf.check_domain(&preimage));
+assert_eq!(a * preimage, target);
+```
 
-- [Preimage Samplable Functions (PSF)](https://github.com/qfall/tools/blob/dev/src/primitive/psf.rs)
-- [Trapdoors](https://github.com/qfall/tools/blob/dev/src/sample/g_trapdoor.rs)
-  - [G-trapdoor incl. short basis](https://github.com/qfall/tools/blob/dev/src/sample/g_trapdoor/gadget_classical.rs)
-  - [Ring-based G-trapdoor incl. short basis](https://github.com/qfall/tools/blob/dev/src/sample/g_trapdoor/gadget_ring.rs)
-- [Utility functions for quick instantiations](https://github.com/qfall/tools/blob/dev/src/utils/)
-  - [Common moduli](https://github.com/qfall/tools/blob/dev/src/utils/common_moduli.rs)
-  - [Rotation matrices](https://github.com/qfall/tools/blob/dev/src/utils/rotation_matrix.rs)
-  - [Common encodings](https://github.com/qfall/tools/blob/dev/src/utils/common_encodings.rs)
+## Bugs
+Please report bugs through the [GitHub issue tracker](https://github.com/qfall/tools/issues).
 
-## License
+## Contributions
+Contributors are:
+- Marvin Beckmann
+- Jan Niklas Siemer
 
-This library is distributed under the **Mozilla Public License Version 2.0** which can be found here [License](https://github.com/qfall/tools/blob/dev/LICENSE).
-Permissions of this weak copyleft license are conditioned on making available source code of licensed files and modifications of those files under the same license (or in certain cases, one of the GNU licenses). Copyright and license notices must be preserved. Contributors provide an express grant of patent rights. However, a larger work using the licensed work may be distributed under different terms and without source code for files added in the larger work.
+See [Contributing](https://github.com/qfall/tools/blob/dev/CONTRIBUTING.md) for details on how to contribute.
 
 ## Citing
 
-Please use the following bibtex entry to cite [qFALL-tools](https://github.com/qfall/tools):
+Please use the following bibtex entry to cite [qFALL](https://qfall.github.io).
 
 ```text
-@misc{qFALL-tools,
-    author = {Porzenheim, Laurens and Beckmann, Marvin and Kramer, Paul and Milewski, Phil and Moog, Sven and Schmidt, Marcel and Siemer, Niklas},
-    title = {qFALL-tools v0.0},
-    howpublished = {Online: \url{https://github.com/qfall/tools}},
-    month = Mar,
-    year = 2023,
-    note = {University Paderborn,  Codes and Cryptography}
-}
+TODO: Update to eprint
 ```
 
-## Get in Touch
+## Dependencies
+This project is based on [qfall-math](https://crates.io/crates/qfall-math), which builds on top of the C-based, optimised math-library [FLINT](https://flintlib.org/). We utilise [serde](https://crates.io/crates/serde) and [serde_json](https://crates.io/crates/serde_json) to (de-)serialize objects to and from JSON. This crate relies on [criterion](https://crates.io/crates/criterion) for benchmarking purposes. An extensive list can be found in our `Cargo.toml` file.
+
+## License
 
-One can contact the members of the project group with our mailing list `pg-qfall(at)lists.upb.de`.
+This library is distributed under the [Mozilla Public License Version 2.0](https://github.com/qfall/tools/blob/dev/LICENSE).
+Permissions of this weak copyleft license are conditioned on making the source code of licensed files and modifications of those files available under the same license (or in certain cases, under one of the GNU licenses). Copyright and license notices must be preserved. Contributors provide an express grant of patent rights. However, a larger work using the licensed work may be distributed under different terms and without source code for files added to the larger work.

benches/psf.rs

@@ -6,10 +6,10 @@
 // the terms of the Mozilla Public License Version 2.0 as published by the
 // Mozilla Foundation. See <https://mozilla.org/en-US/MPL/2.0/>.
 
-use criterion::{criterion_group, Criterion};
+use criterion::{Criterion, criterion_group};
 use qfall_math::{integer_mod_q::MatZq, rational::Q};
 use qfall_tools::{
-    primitive::psf::{PSFPerturbation, PSF, PSFGPV},
+    primitive::psf::{PSF, PSFGPV, PSFPerturbation},
     sample::g_trapdoor::gadget_parameters::GadgetParameters,
 };
 

src/compression.rs

@@ -0,0 +1,19 @@
+// Copyright © 2025 Niklas Siemer
+//
+// This file is part of qFALL-tools.
+//
+// qFALL-tools is free software: you can redistribute it and/or modify it under
+// the terms of the Mozilla Public License Version 2.0 as published by the
+// Mozilla Foundation. See <https://mozilla.org/en-US/MPL/2.0/>.
+
+//! Contains commonly used compression techniques in lattice-based cryptography.
+//!
+//! References:
+//! - \[1\] National Institute of Standards and Technology (2024).
+//!   Module-Lattice-Based Key-Encapsulation Mechanism Standard.
+//!   Federal Information Processing Standards Publication (FIPS 203).
+//!   <https://doi.org/10.6028/NIST.FIPS.203>
+
+mod lossy_compression_fips203;
+
+pub use lossy_compression_fips203::LossyCompressionFIPS203;