-
Notifications
You must be signed in to change notification settings - Fork 479
Coding conventions
Subdirectories of src contain modules. The first component of a module name is the type of module it is, either sig for digital signatures, or kem for a key encapsulation method.
-
For sigs, every module uses the algorithm name in the
liboqs/src/sigdirectory. -
For key encapsulation methods, every module uses the algorithm name in
liboqs/src/kem.
-
TODO: for sigs there's something odd with src/sig/sig_[algorithm] and src/sig/[algorithm]
-
For key encapsulation methods, every module uses the algorithm name
liboqs/src/kem.
Public functions are intended to be used by calling applications/libraries, and are exported in .h files. Public functions start with upper-case letters and take the form OQS_KEM_... or OQS_SIG_....
Private functions that still have global scope are functions which might be meaningful on their own, and could be useful to another research, but are not generally intended to be used by calling applications/libraries. They might be tested independently by a test hardness. Private functions with global scope start with lower-case letters and are of the form oqs_sig_... or oqs_kem_....
Private functions that do not have global scope can be named in any way. However, they must be declared static to avoid polluting the global namespace. You can check to make sure you haven't missed any such functions by ensuring the following command gives empty output:
nm -g liboqs.a | grep ' T ' | grep -E -v -i ' T [_]?[OQS|ntru]'
Code will be compiled using -std=c99. The code should compile cleanly—without warnings—with the following compiler flags:
-Wpedantic -Wall -Wextra
Memory involving secrets (secret keys, derived shared secrets) should be explicitly zeroed-out once it is not longer required. OQS_MEM_cleanse should be used to zero-out memory on the stack; OQS_MEM_secure_free should be used to zero-out and deallocate memory on the heap. Note that you should use one of these two instead of directly calling memset or bzero: an optimizing compiler may optimize out the seemingly "unnecessary" call to be memset or bzero, whereas we have taken steps in our two functions to prevent that from happening.
To indicate success/failure, functions should return the type OQS_STATUS, which is an enum defined in src/common/common.h. New error codes can be added for distinguishing new error types as required. New error codes should have numbers manually assigned to them (for consistency over time as new errors are added), and should be grouped (eg., reserve -100..-199 for errors related to some Algorithm A, -200..-299 for errors related to some Algorithm B, etc.).
Callers should compare with the symbol rather than the individual value. For example,
ret = OQS_KEM_encaps(...);
if (ret == OQS_SUCCESS) { ... }Source code should be formatted using the make prettyprint target before committing. We use clang-format for consistent formatting. However, there are inconsistencies between versions of clang-format, so we have currently fixed our version of clang-format to version 3.9
To install and use clang-format 3.9 on Ubuntu:
- Try
sudo apt install clang-format-3.9 - If that doesn't work, try following the commands in our script .travis/install-clang-format.sh
To install and use clang-format 3.9 on macOS using brew:
brew unlink clang-formatbrew install https://raw.githubusercontent.com/Homebrew/homebrew-core/0c4314c499576b28e4c082b591228a8f940954c0/Formula/clang-format.rb
Inline documentation in .c and .h files is done using Doxygen.