# Developer guidelines Please read carefully before contributing to this repo. ## Code structure The code is split into the modules below: - `common`: common code for AES, SHAKE, (P)RNG, memory handling. Every module that needs a hash function, seed expansion (e.g., KLPT), deterministic alea for tests, should call to this module. - `uintbig`: multi-precision big integers. - `gf`: GF(p^2) and GF(p) arithmetic. - `ec`: elliptic curves, isogenies and pairings. Everything that is purely finite-fieldy. - `quaternion`: quaternion orders and ideals. This is, essentially, replacing PARI/GP. - `klpt`: implementation of KLPT. - `id2iso`: code for Iso <-> Ideal. - `util`: auxilary code shared among libraries. The sources for the modules are in [`src/`](src). Each module is structured as follows: ``` SQIsign └── src └── ├── │ ├── generic │ └── lvl1 ├── opt │ ├── generic │ ├── lvl1 │ ├── lvl1_var1 │ ├── lvl3 │ └── lvl5 └── ref └── generic ``` where: - `` is the name of the module. - `` are optional architecture-specific implementations of the module (e.g., `broadwell` for code using assembly instructions specific to the Broadwell platform). - `opt` and `ref` are the portable *optimized* and *reference* implementations. - `lvl1`, `lvl3`, `lvl5` are parameter-dependent implementations of the module, corresponding to NIST levels 1, 3 and 5, respectively. - `lvl1_var1` is a variant of `lvl1`, e.g., using a different prime characteristic. The naming is free, and implementors are encouraged to choose more explicit naming, e.g., `lvl1_varp6983` for the variant using the `p6983` prime defined in the SQIsign AC20 variant. - `generic` is a parameter-independent implementation of the module. If no folder is named like the currently selected variant (see [Build](README.md#Build)), then this is compiled instead. Each of the folders above is allowed to be a symlink. E.g., if a module has no separate optimized and reference implementation, then `opt` can be a symlink to `ref`. Other example: a module's code only depends on the field size, but not the specific prime, then `lvl1_varp6983` could be a symlink to `lvl1`. ### Contents of a module The leaf folders described above should arrange code as described below. We use the `generic` implementation of the `uintbig` module as an example. ``` generic ├── bench │ ├── CmakeLists.txt │ ├── bench1.c │ └── bench2.c ├── include │ └── uintbig.h ├── test │ ├── CmakeLists.txt │ ├── test1.c │ └── test2.c ├── CmakeLists.txt ├── internal_header.h ├── soruce1.c └── soruce2.c ``` where: - `include/` shall contain a **unique header file** named `.h`, where `` is the name of the module. This header contains the public API of the module, and is the only header that can be included by other modules (e.g., via `#include `). These files must contain extensive doxygen-formatted documentation describing the module, see [Documentation](#Documentation). - `bench` and `test` contain one executable per file, containing, well, benchmarks and unit tests. Refer to [Benchmarks](#Benchmarks) and [Tests](#Tests) for instructions on how to write these. - Internal headers for the private use of the module, such as `internal_header.h` go to the root. Include these using `#include "internal_header.h"`. - The implementation of the module also goes into the root. ## Tests It is important to have extensive test coverage of the whole software. Each module must have its own unit tests, as well as integration tests to ensure consistency across the modules. ### Unit tests These go into `src////test/`. Refer to ... for an example of how to write tests. ### Integration tests These go into `test/`. Refer to [`test/test_sqisign.c`](test/test_sqisign.c) for an example. ### Known Answer Tests (KAT) KATs help validate consistency across implementations. By ensuring that, e.g., the optimized and reference implementation produce the same signatures. See [Known Answer Tests in README.md](README.md#Known Answer Tests (KAT)). ## Benchmarks Benchmarks for a module go into `src////bench/`. Global benchmarks go... ## Documentation Use [Doxygen headers](https://www.doxygen.nl/manual/docblocks.html) for documentation. All code should be extensively documented. The public module headers **MUST** be thoroughly documented. CI automatically builds a PDF of the doc every time code is pushed. To download the PDF, go to [Actions](https://github.com/SQIsign/sqisign-nist/actions), click on the workflow run you're interested in, then go to Artifacts -> docs (see figure). ![](https://user-images.githubusercontent.com/149199/231756751-0f2780f8-33fe-4db9-8800-b5f145423b65.png) ## Branches and pull requests Always work on topic branches, never push work in progress on the `main` branch. Once a task / issue / work unit is completed, create a pull-request and ask your team leader for a review. ## Coding style - **C version**: All code must compile cleanly as *C99*, without emitting any warnings, using recent versions of GCC and clang. - **Names**: Externally visible functions and types should be prefixed with the name of the module they belong to. - **Aliases**: Do use `typedef` with descriptive names whenever it makes any nonzero amount of sense to do so. Avoid `typedef`s for things other than `struct`s (or elementary data types); they have a tendency to break for array and pointer types if programmers are not aware of the nature of the underlying type. - **Parameters**: Output arguments, if any, should always come first. Input arguments should generally be marked `const`. Objects of types which typically fit into registers should be passed and returned by value, larger objects by reference (i.e., as a pointer). If certain arguments often appear together, it may be an indication that they should be wrapped as a `struct`. - **Global variables**: Global *constants* are acceptable if needed, especially within modules whose code already implicitly relies on the same constants anyway (primary example: 𝔽ₚ). It is often a good idea to group global constants in a meaningful `struct` and write the code such that the struct could easily be replaced by a runtime variable at a later point. Global *state* (modifiable global variables), on the other hand, is strictly forbidden. - **Whitespace**: Try not to mix tabs and spaces. Line endings should be UNIX-style (i.e., `\n` rather than `\r\n`). Whitespace characters at the end of a line, or by themselves on an otherwise empty line, are to be avoided.