You want to help improve OpenSSE, and in particular it cryptographic toolkit. Great! Welcome onboard. Read the following sections to know what you can do, and how you can work on this project.
Following these guidelines helps the maintainers of the project by saving their time and will allow them to help you with the possible issues you might encounter while contributing to this project.
- Make sure you have a GitHub account (please, use 2FA!)
- Take a look at the following documentation ⬇️
- See if the bug you want to report has not already been reported or fixed on the issue page (maybe even look in the closed ones).
If you have found a bug (or what you believe to be a bug), please report it! And maybe even fix it. Note that we treat differently bugs enabling security vulnerabilities and other kinds of bugs.
If you found a vulnerability, do NOT open an issue. Email the principal author, and if you can encrypt your mail using his GPG public key (this can easily be done using Keybase).
A security vulnerability is a bug which might allow an attacker to access confidential data that is not his, or deny legitimate users access to their data.
For regular bugs, please open a new issue. In the issue, state the environnement you are working on (mainly the OS and the compiler), and carefully describe how to reproduce the bug (this is very important in order to correctly locate and fix the bug).
Also, make sure to tag the issue appropriately (e.g. by using the bug and compilation labels if you ran into a compilation problem). Similarly, a concise, yet descriptive title helps a lot.
The philosophy of this project is to provide the cryptographic primitives that can be useful when implementing some searchable encryption schemes. When possible, we rely on robust, well studied and proved instantiations of these cryptographic tools.
Also, we aim at providing a secure implementations of the cryptographic schemes proposed, and an API that prevents any kind of misuse by a distracted developer. As an example, you can see in the code that instances of the C++ classes implementing symmetric primitives cannot be copied. Similarly, the Key objects can only be moved, not copied, ensuring that only one copy of the key is in memory. Also, the destructor of the Key class wipes out buffer containing this key.
Proposal for new cryptographic primitives must follow these ideas, and must pass the following checklist:
- Is the primitive useful for implementation of searchable encryption schemes?
- Is there any cryptographically robust realization of this primitive (i.e. relying on well known and well understood assumptions)?
To submit a new feature or and enhancement, open an issue, choose a simple and descriptive title, and carefully describe it.
If you want to contribute to this project by writing some code, fork the repo and make sure you can compile the existing code by following the instructions in the README.
You can know work on your copy of the code (working on a separate branch for your changes is a good idea). Once you are done, submit a pull request.
The code of your PR will be reviewed by one other contributor. However, before submitting a PR, make sure that
- All the unit tests pass, and that your contribution is covered by existing or new tests;
- The static analysers do not raise any warning (cf. next section).
- The ASan and UBSan sanitizers do not raise any error when running the unit tests (cf. next section).
- The code is correctly formatted (use clang-format).
In the scripts directory, you will find two shell scripts useful to run the clang-tidy and cppcheck static analysis tools.
They must be available on your machine.
cppcheck is very easy to install on Debian/Ubuntu, Fedora, or Mac OS (cf. the instructions on the cppcheck website). For clang-tidy, you might have to download the last stable version of clang and LLVM from the LLVM download page.
It is very easy to enable the adress and undefined behavior sanitizers.
Just call the SConstruct build script with, respectively, the options sanitize_address=1 and sanitize_undefined=1.