CONTRIBUTING.md

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, qFALL-tools and 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.
• 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.
• If you implement a construction, e.g., Kyber, then add your code to 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. 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.

cargo doc --open

Furthermore, here is an example of a doc-comment of a function that follows our guidelines.

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> {...}
}