diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8cd3bf9 --- /dev/null +++ b/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. + /// + pub fn sample_discrete_gauss(center: impl Into, s: impl Into) -> Result {...} +} +``` \ No newline at end of file diff --git a/benches/README.md b/benches/README.md index 90523c7..7a3e66d 100644 --- a/benches/README.md +++ b/benches/README.md @@ -43,7 +43,17 @@ You can also run the benchmarks using the profiler flamegraph. Details can be fo - [Flamegraph GitHub](https://github.com/flamegraph-rs/flamegraph). This provides insights on the execution time of the executed functions and their subroutines. -Note: Flamegraph does not work in WSL +### Installing Flamegraph + +Installing Flamegraph in Linux and macOS is easy, since you only need to install flamegraph using `cargo install flamegraph`. +But in WSL you need some more steps, since you need to install "perf" manually. + +So after `cargo install flamegraph`, you need to update "apt" with `sudo apt update` and install "build-essential's" by `sudo apt install -y build-essential libelf-dev libnuma-dev flex bison libdw-dev libunwind-dev libaudit-dev libslang2-dev libperl-dev python3-dev binutils-dev liblzma-dev libiberty-dev`.
+Then you go into the home directory with `cd ~` and install the linux kernel with
+`wget - https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.15.5.tar.xz` (Adjust the version as needed).
+After that you extract it with `tar -xvf linux-5.15.5.tar.xz` and move into "perf" with `cd linux-5.15.5/tools/perf` +there you use `make` to compile it. +The last step is to make "perf" visible by e.g. `sudo cp ./perf /usr/local/bin/`. ### Command